安装

前提条件

React Compiler 的设计目标是与 React 19 配合得最好，但它也支持 React 17 和 18。了解更多关于React 版本兼容性。

安装

将 React Compiler 作为 devDependency 安装：

npm install -D babel-plugin-react-compiler@latest

或者使用 Yarn：

yarn add -D babel-plugin-react-compiler@latest

或者使用 pnpm：

pnpm install -D babel-plugin-react-compiler@latest

基本设置

React Compiler 的设计目标是默认即可工作，无需任何配置。不过，如果你需要在特殊情况下对其进行配置（例如，面向低于 19 的 React 版本），请参阅编译器选项参考。

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

Babel

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

module.exports = {
  plugins: [
    'babel-plugin-react-compiler', // 必须最先运行！
    // ... 其他插件
  ],
  // ... 其他配置
};

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 插件：

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 插件添加到其中：

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"], // 如果你使用 TypeScript
        plugins: [
          ["babel-plugin-react-compiler", ReactCompilerConfig],
        ],
      },
    }),
  ],
});

Webpack

社区维护的 webpack loader 现已可用。

Expo

请参阅 Expo 文档 以在 Expo 应用中启用并使用 React Compiler。

Metro (React Native)

React Native 通过 Metro 使用 Babel，因此请参阅使用 Babel 部分了解安装说明。

Rspack

请参阅 Rspack 文档 以在 Rspack 应用中启用并使用 React Compiler。

Rsbuild

请参阅 Rsbuild 文档 以在 Rsbuild 应用中启用并使用 React Compiler。

ESLint 集成

React Compiler 包含一条 ESLint 规则，可帮助识别无法优化的代码。当 ESLint 规则报告错误时，这意味着编译器会跳过对该特定组件或 hook 的优化。这是安全的：编译器会继续优化代码库的其他部分。你不需要立即修复所有违规项。可以按自己的节奏逐步处理它们，以逐渐增加可优化组件的数量。

安装 ESLint 插件：

npm install -D eslint-plugin-react-hooks@latest

如果你还没有配置 eslint-plugin-react-hooks，请按照 readme 中的安装说明 进行设置。编译器规则可在 recommended-latest 预设中使用。

ESLint 规则将会：

• 识别React 规则的违规项
• 显示哪些组件无法被优化
• 提供有助于修复问题的错误信息

验证你的设置

安装完成后，请验证 React Compiler 是否正常工作。

检查 React DevTools

被 React Compiler 优化的组件会在 React DevTools 中显示一个 “Memo ✨” 徽标：

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

如果编译器正常工作：

• 组件会在 React DevTools 中显示 “Memo ✨” 徽标
• 昂贵的计算会自动进行 memoization
• 不需要手动使用 useMemo

检查构建输出

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

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";
  // 组件代码写在这里
}

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

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

后续步骤

现在你已经安装了 React Compiler，了解更多关于：

• React 版本兼容性 适用于 React 17 和 18
• 配置选项 用于自定义编译器
• 渐进式采用策略 适用于现有代码库
• 调试技巧 用于排查问题
• 编译库指南 用于编译你的 React 库