大网数据广告活动
React 前端开发

编译库

· 52CE 我爱测

为了确保兼容性,你应该对编译和未编译两种情况下的库都进行测试。在编译后的代码上运行你现有的测试套件,并创建一个绕过编译器的独立测试配置。这有助于捕获任何可能由编译过程引起的问题,并确保你的库在所有场景下都能正常工作

本指南旨在帮助库作者理解如何使用 React 编译器来为用户提供经过优化的库代码。

为什么要发布编译后的代码? {/why-ship-compiled-code/}

作为库作者,你可以在将代码发布到 npm 之前编译。这样做有几个好处:

  • 为所有用户提升性能 —— 即使用户尚未使用 React 编译器,他们也能从你的库中获得优化后的代码。
  • 用户无需配置 —— 这些优化开箱即用
  • 行为一致 —— 无论用户的构建设置如何,他们都能获得相同版本的优化代码

设置编译 {/setting-up-compilation/}

将 React 编译器添加到你的库的构建过程中:

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

配置你的构建工具来编译你的库。例如,使用 Babel:

// babel.config.js
module.exports = {
  plugins: [
    'babel-plugin-react-compiler',
  ],
  // ... 其他配置
};

向下兼容性 {/backwards-compatibility/}

如果你的库需要支持 React 19 以下的版本,你需要进行额外的配置:

1. 安装运行时包 {/install-runtime-package/}

我们推荐将 react-compiler-runtime 作为直接依赖安装:

npm install react-compiler-runtime@latest
{
  "dependencies": {
    "react-compiler-runtime": "^1.0.0"
  },
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}

2. 配置目标版本 {/configure-target-version/}

设置你的库所支持的最低 React 版本:

{
  target: '17', // 最低支持的 React 版本
}

测试策略 {/testing-strategy/}

为了确保兼容性,你应该对编译和未编译两种情况下的库都进行测试。在编译后的代码上运行你现有的测试套件,并创建一个绕过编译器的独立测试配置。这有助于捕获任何可能由编译过程引起的问题,并确保你的库在所有场景下都能正常工作

故障排除 {/troubleshooting/}

库在旧版 React 中无法工作 {/library-doesnt-work-with-older-react-versions/}

如果你编译后的库在 React 17 或 18 中抛出错误:

  1. 确认你已将 react-compiler-runtime 安装为生产依赖
  2. 检查你的 target 配置是否与你支持的最低 React 版本匹配
  3. 确保运行时包已包含在你最终发布的打包中

编译过程与其他 Babel 插件冲突 {/compilation-conflicts-with-other-babel-plugins/}

某些 Babel 插件可能与 React 编译器存在冲突:

  1. 将 babel-plugin-react-compiler 放在插件列表的靠前位置
  2. 在其他插件中禁用可能引起冲突的优化选项
  3. 对你的构建输出进行彻底的测试

找不到运行时模块 {/runtime-module-not-found/}

如果用户遇到 “Cannot find module 'react-compiler-runtime'” 错误:

  1. 确保该运行时包被列在 dependencies 中,而不是 devDependencies
  2. 检查你的打包工具是否将该运行时包含在了输出中
  3. 确认这个包已经和你的库一起成功发布到了 npm

Next Steps {/next-steps/}

本文来自 React 文档中文译者及贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
React 文档中文译者及贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。