安装 React 编译器

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

在本教程中，你将学习：

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

前提条件 {/prerequisites/}

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

安装 {/installation/}

将 React 编译器安装为 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

基本设置 {/basic-setup/}

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

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

陷阱

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

Babel {/babel/}

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

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

Vite {/vite/}

如果你使用 Vite v6.0.0 或者更高版本，那么可以从 @vitejs/plugin-react 中导出并配置 reactCompilerPreset：

npm install -D @rolldown/plugin-babel

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

export default defineConfig({
  plugins: [
    react(),
    babel({
      presets: [reactCompilerPreset()]
    }),
  ],
});

注意

从 @vitejs/plugin-react@6.0.0 开始，内联的 Babel 选项已经被移除。如果你使用的是更低版本，可以通过下面的方式进行配置：

js 复制代码

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

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

或者，你也可以通过 @rolldown/plugin-babel 直接使用 Babel 插件。

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

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

Next.js {/usage-with-nextjs/}

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

React Router {/usage-with-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 {/usage-with-webpack/}

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

Expo {/usage-with-expo/}

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

Metro (React Native) {/usage-with-react-native-metro/}

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

Rspack {/usage-with-rspack/}

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

Rsbuild {/usage-with-rsbuild/}

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

ESLint 集成 {/eslint-integration/}

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

安装 ESLint 插件：

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

如果你尚未配置好 eslint-plugin-react-hooks，请参考其 README 的安装说明 来进行配置。编译器规则可在 recommended-latest 预设中找到。

ESLint 规则将会：

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

验证你的设置 {/verify-your-setup/}

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

检查 React DevTools {/check-react-devtools/}

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

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

如果编译器正在工作：

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

检查构建输出 {/check-build-output/}

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

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" 指令暂时将其排除：

function ProblematicComponent() {
  "use no memo";
  // 这里是组件代码
}

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

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

下一步 {/next-steps/}

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

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