本指南将帮助你在 React 应用程序中安装和配置 React Compiler。

你将会学习到

  • 如何安装 React 编译器
  • 不同构建工具的基本配置
  • 如何验证你的设置是否正常工作

前提条件

React 编译器专为与 React 19 配合使用而设计,但也支持 React 17 和 18。了解有关 React 版本兼容性 的更多信息。

注意

React Compiler 当前处于 RC 阶段。请使用 @rc 标签安装,以获取最新的发布候选版本。

安装

将 React 编译器安装为 devDependency

Terminal
npm install -D babel-plugin-react-compiler@rc

或者使用 Yarn:

Terminal
yarn add -D babel-plugin-react-compiler@rc

或者使用 pnpm:

Terminal
pnpm install -D babel-plugin-react-compiler@rc

基本设置

React Compiler 默认无需任何配置即可工作。不过,如果你需要在特殊情况下进行配置(例如,要支持低于 19 版本的 React),请参考编译器选项参考文档

设置过程取决于你使用的构建工具。React Compiler 包含一个 Babel 插件,可以集成到你的构建流程中。

陷阱

React Compiler 必须在你的 Babel 插件管道中 首先 运行。编译器需要原始的源代码信息来进行正确的分析,因此它必须在其他转换操作之前处理你的代码。

Babel

创建或更新你的 babel.config.js

module.exports = {
plugins: [
'babel-plugin-react-compiler', // must run first!
// ... other plugins
],
// ... other config
};

Vite

如果你使用 Vite,可以将插件添加到 vite-plugin-react 中:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
plugins: [
react({
babel: {
plugins: ['babel-plugin-react-compiler'],
},
}),
],
});

或者,如果你更倾向于为 Vite 使用一个独立的 Babel 插件:

Terminal
npm install -D vite-plugin-babel
// vite.config.js
import babel from 'vite-plugin-babel';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
plugins: [
react(),
babel({
babelConfig: {
plugins: ['babel-plugin-react-compiler'],
},
}),
],
});

Next.js

更多信息请参考 Next.js 文档

React Router

安装 vite-plugin-babel,并将其编译器的 Babel 插件添加到其中:

Terminal
npm install vite-plugin-babel
// vite.config.js
import { defineConfig } from "vite";
import babel from "vite-plugin-babel";
import { reactRouter } from "@react-router/dev/vite";

const ReactCompilerConfig = { /* ... */ };

export default defineConfig({
plugins: [
reactRouter(),
babel({
filter: /\.[jt]sx?$/,
babelConfig: {
presets: ["@babel/preset-typescript"], // if you use TypeScript
plugins: [
["babel-plugin-react-compiler", ReactCompilerConfig],
],
},
}),
],
});

Webpack

社区开发的 webpack loader 现在可以从这里获取。

Expo

请参考 Expo 文档 以了解如何在 Expo 应用中启用并使用 React 编译器。

Metro (React Native)

React Native 通过 Metro 使用 Babel,因此请参考 与 Babel 配合使用 章节获取安装说明。

Rspack

请参考 Rspack 文档 以了解如何在 Rspack 应用中启用并使用 React 编译器。

Rsbuild

请参考 Rsbuild 文档 以了解如何在 Rsbuild 应用中启用并使用 React 编译器。

ESLint Integration

React Compiler 包含一条 ESLint 规则,可帮助识别无法优化的代码。当 ESLint 规则报告错误时,意味着编译器将跳过对该特定组件或 Hook 的优化。这是安全的:编译器将继续优化代码库的其他部分。你不需要立即修复所有违规之处。可以按照自己的节奏逐步解决这些问题,以逐渐增加已优化组件的数量。

安装 ESLint 插件:

Terminal
npm install -D eslint-plugin-react-hooks@rc

然后在你的 ESLint 配置中启用编译器规则:

// .eslintrc.js
module.exports = {
rules: {
'react-hooks/react-compiler': 'error',
},
};

ESLint 规则将会:

  • 识别对 React 规则 的违反情况
  • 显示哪些组件无法被优化
  • 提供有用的错误信息来帮助修复问题

验证你的设置

安装后,请验证 React 编译器是否正常工作。

检查 React DevTools

由 React 编译器优化的组件会在 React DevTools 中显示一个 “Memo ✨” 徽章:

  1. 安装 React Developer Tools 浏览器扩展
  2. 在开发模式下打开你的应用
  3. 打开 React DevTools
  4. 查看组件名称旁边的 ✨ 表情符号

如果编译器正在工作:

  • 组件将在 React DevTools 中显示一个 “Memo ✨” 徽章
  • 昂贵的计算将自动被记忆化
  • 无需手动使用 useMemo

检查构建输出

你还可以通过检查构建输出来验证编译器是否正在运行。编译后的代码将包含编译器自动添加的自动记忆化逻辑。

import { c as _c } from "react/compiler-runtime";
export default function MyApp() {
const $ = _c(1);
let t0;
if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
t0 = <div>Hello World</div>;
$[0] = t0;
} else {
t0 = $[0];
}
return t0;
}

故障排除

排除特定组件

如果某个组件在编译后引发问题,可以使用 "use no memo" 指令暂时将其排除:

function ProblematicComponent() {
"use no memo";
// Component code here
}

这会告诉编译器跳过对该特定组件的优化。你应该修复根本问题,并在解决后移除该指令。

如需更多故障排除帮助,请参阅调试指南

下一步

既然你已经安装了 React 编译器,可以进一步了解以下内容: