本指南将帮助你在 React 应用中安装和配置 React 编译器。

你将学习到

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

先决条件

🌐 Prerequisites

React 编译器设计为与 React 19 最兼容，但它也支持 React 17 和 18。了解更多关于 React 版本兼容性 的信息。

🌐 React Compiler is designed to work best with React 19, but it also supports React 17 and 18. Learn more about React version compatibility.

安装

🌐 Installation

将 React 编译器安装为 devDependency:

🌐 Install React Compiler as a devDependency:

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

或使用 Yarn：

🌐 Or with Yarn:

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

或使用 pnpm：

🌐 Or with pnpm:

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

基本设置

🌐 Basic Setup

React 编译器设计为默认情况下无需任何配置即可工作。但是，如果你在特殊情况下需要配置它（例如，针对低于 19 的 React 版本），请参考 编译器选项参考。

🌐 React Compiler is designed to work by default without any configuration. However, if you need to configure it in special circumstances (for example, to target React versions below 19), refer to the compiler options reference.

设置过程取决于你的构建工具。React 编译器包括一个 Babel 插件，可以与你的构建流程集成。

🌐 The setup process depends on your build tool. React Compiler includes a Babel plugin that integrates with your build pipeline.

易犯错误

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

Babel

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

🌐 Create or update your babel.config.js:

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

Vite

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

🌐 If you use Vite, you can add the plugin to 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 插件：

🌐 Alternatively, if you prefer a separate Babel plugin for Vite:

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 文档 了解更多信息。

🌐 Please refer to the Next.js docs for more information.

React Router

安装 vite-plugin-babel，并向其添加编译器的 Babel 插件：

🌐 Install vite-plugin-babel, and add the compiler’s Babel plugin to it:

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 加载器现在可以在这里获得。

🌐 A community webpack loader is now available here.

Expo

请参考 Expo 的文档 来在 Expo 应用中启用和使用 React 编译器。

🌐 Please refer to Expo’s docs to enable and use the React Compiler in Expo apps.

Metro (React Native)

React Native 通过 Metro 使用 Babel，因此请参阅 Usage with Babel 部分以获取安装说明。

🌐 React Native uses Babel via Metro, so refer to the Usage with Babel section for installation instructions.

Rspack

请参阅 Rspack 的文档 以在 Rspack 应用中启用和使用 React 编译器。

🌐 Please refer to Rspack’s docs to enable and use the React Compiler in Rspack apps.

Rsbuild

请参考 Rsbuild 的文档 来在 Rsbuild 应用中启用和使用 React 编译器。

🌐 Please refer to Rsbuild’s docs to enable and use the React Compiler in Rsbuild apps.

ESLint 集成

🌐 ESLint Integration

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

🌐 React Compiler includes an ESLint rule that helps identify code that can’t be optimized. When the ESLint rule reports an error, it means the compiler will skip optimizing that specific component or hook. This is safe: the compiler will continue optimizing other parts of your codebase. You don’t need to fix all violations immediately. Address them at your own pace to gradually increase the number of optimized components.

安装 ESLint 插件：

🌐 Install the ESLint plugin:

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

如果你还没有配置 eslint-plugin-react-hooks，请按照 自述文件中的安装说明 操作。编译器规则在 recommended-latest 预设中可用。

🌐 If you haven’t already configured eslint-plugin-react-hooks, follow the installation instructions in the readme. The compiler rules are available in the recommended-latest preset.

ESLint 规则将：

🌐 The ESLint rule will:

  • 识别违反React 规则的行为
  • 显示哪些组件无法优化
  • 提供有助于解决问题的错误消息

验证你的设置

🌐 Verify Your Setup

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

🌐 After installation, verify that React Compiler is working correctly.

检查 React DevTools

🌐 Check React DevTools

由 React 编译器优化的组件将在 React 开发者工具中显示“Memo ✨”徽章：

🌐 Components optimized by React Compiler will show a “Memo ✨” badge in React DevTools:

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

如果编译器正常运行：

🌐 If the compiler is working:

  • 组件将在 React DevTools 中显示 “Memo ✨” 徽章
  • 昂贵的计算将被自动记忆
  • 不需要手动 useMemo

检查构建输出

🌐 Check Build Output

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

🌐 You can also verify the compiler is running by checking your build output. The compiled code will include automatic memoization logic that the compiler adds automatically.

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;
}

故障排除

🌐 Troubleshooting

禁用特定组件

🌐 Opting out specific components

如果某个组件在编译后出现问题，你可以使用 "use no memo" 指令暂时将其排除：

🌐 If a component is causing issues after compilation, you can temporarily opt it out using the "use no memo" directive:

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

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

🌐 This tells the compiler to skip optimization for this specific component. You should fix the underlying issue and remove the directive once resolved.

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

🌐 For more troubleshooting help, see the debugging guide.

下一步

🌐 Next Steps

现在你已经安装了 React Compiler，请了解更多信息：

🌐 Now that you have React Compiler installed, learn more about:

上一章简介
下一章增量采用