安装

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

先决条件

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 设计为默认无需任何配置即可工作。但是，如果您需要在特殊情况下配置它（例如，针对 React 19 以下的版本），请参考编译器选项参考。

设置过程取决于您的构建工具。React Compiler 包含一个与您的构建管道集成的 Babel 插件。

Babel

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

Vite

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

或者，如果您更喜欢为 Vite 使用单独的 Babel 插件：

npm install -D vite-plugin-babel

Next.js

请参考js 文档了解更多信息。

React Router

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

npm install vite-plugin-babel

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 规则报告错误时，意味着编译器将跳过优化该特定组件或钩子。这是安全的：编译器将继续优化代码库的其他部分。您无需立即修复所有违规。您可以按照自己的节奏处理它们，以逐步增加优化组件的数量。

安装 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 ✨”徽章
• 昂贵的计算将被自动记忆化
• 无需手动使用useMemo

检查构建输出

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

故障排除

选择退出特定组件

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

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

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

后续步骤

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

• React 版本兼容性（适用于 React 17 和 18）
• 配置选项以自定义编译器
• 增量采用策略（适用于现有代码库）
• 调试技术以排查问题
• 编译库指南（用于编译您的 React 库）