跳至主内容
版本：0.78

React Native Gradle 插件

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

本文档将指导您如何为 Android 平台构建 React Native 应用时配置 React Native Gradle 插件（通常简称为 RNGP）。

使用插件​

React Native Gradle 插件以独立 NPM 包形式分发，安装 react-native 时会自动安装该插件。

通过 npx react-native init 创建的新项目已自动配置此插件。若您使用此命令创建应用，无需额外安装步骤。

若需将 React Native 集成至现有项目，请参考集成指南：其中包含插件安装的具体说明。

配置插件​

默认情况下插件采用开箱即用的合理配置。仅当需要定制功能时，才需参考本文档调整配置。

您可在 android/app/build.gradle 文件中的 react 代码块内修改配置：

groovy
apply plugin: "com.facebook.react"

/**
 * This is the configuration block to customize your React Native Android app.
 * By default you don't need to apply any configuration, just uncomment the lines you need.
 */
react {
  // Custom configuration goes here.
}

各配置项说明如下：

root​

此配置指向 React Native 项目根目录（即包含 package.json 的目录）。默认为 ..。可按如下方式自定义：

groovy
root = file("../")

reactNativeDir​

此配置指定 react-native 包的安装目录。默认为 ../node_modules/react-native。 若使用 monorepo 或其他包管理器，可按需调整 reactNativeDir 配置项。

可按如下方式配置：

groovy
reactNativeDir = file("../node_modules/react-native")

codegenDir​

此配置指定 react-native-codegen 包的安装目录。默认为 ../node_modules/react-native-codegen。 若使用 monorepo 或其他包管理器，可按需调整 codegenDir 配置。

可按如下方式配置：

groovy
codegenDir = file("../node_modules/@react-native/codegen")

cliFile​

此配置指向 React Native CLI 的入口文件。默认为 ../node_modules/react-native/cli.js。 插件需通过此入口文件调用 CLI 进行打包和应用构建。

若使用 monorepo 或其他包管理器，可按需调整 cliFile：

groovy
cliFile = file("../node_modules/react-native/cli.js")

debuggableVariants​

此配置定义可调试的构建变体列表（关于变体的详细说明请参阅使用变体章节）。

默认情况下插件仅将 debug 变体视为 debuggableVariants（可调试），而 release 则不是。若存在其他变体（如 staging、lite 等），需手动添加至此配置。

标记为 debuggableVariants 的变体不会包含预编译包，因此需运行 Metro 服务才能使用。

可按如下方式配置：

groovy
debuggableVariants = ["liteDebug", "prodDebug"]

nodeExecutableAndArgs​

此配置定义执行脚本时调用的 node 命令及参数。默认为 [node]，可按需添加额外参数：

groovy
nodeExecutableAndArgs = ["node"]

bundleCommand​

此配置指定创建应用包时调用的 bundle 命令名称。使用 RAM Bundles 时尤其有用。默认为 bundle，可按需添加参数：

groovy
bundleCommand = "ram-bundle"

bundleConfig​

此配置指向传递给 bundle --config <file> 的配置文件路径。默认为空（不使用配置文件）。关于打包配置文件的详细信息请参阅CLI 文档。配置示例：

groovy
bundleConfig = file(../rn-cli.config.js)

bundleAssetName​

此配置定义生成的包文件名称。默认为 index.android.bundle。配置示例：

groovy
bundleAssetName = "MyApplication.android.bundle"

entryFile​

此配置指定打包使用的入口文件。默认会查找 index.android.js 或 index.js。配置示例：

groovy
entryFile = file("../js/MyApplication.android.js")

extraPackagerArgs​

此配置定义传递给 bundle 命令的额外参数列表。可用参数详见 CLI 文档。默认为空列表。配置示例：

groovy
extraPackagerArgs = []

hermesCommand​

此配置指向 Hermes 编译器 (hermesc) 的路径。React Native 已内置 Hermes 编译器，通常无需自定义。插件默认会为您的系统选择正确的编译器版本。

hermesFlags​

此配置定义传递给 hermesc 的参数列表。默认为 ["-O", "-output-source-map"]。配置示例：

groovy
hermesFlags = ["-O", "-output-source-map"]

使用产品风味与构建变体​

构建 Android 应用时，可通过自定义产品风味基于同一项目生成不同版本的应用。

请参考 Android 官方指南配置自定义构建类型（如 staging）或产品风味（如 full、lite 等）。 新建项目默认包含两种构建类型（debug 和 release），无自定义产品风味。

所有构建类型与产品风味的组合将生成构建变体。例如存在 debug/staging/release 构建类型和 full/lite 产品风味时，将产生 6 种构建变体：fullDebug、fullStaging、fullRelease 等。

若使用除 debug 和 release 外的自定义变体，需通过 debuggableVariants 配置明确指定哪些变体可调试：

diff
apply plugin: "com.facebook.react"

react {
+ debuggableVariants = ["fullStaging", "fullDebug"]
}

此配置至关重要，因为插件会跳过所有 debuggableVariants 的 JS 包编译步骤——这些变体需依赖 Metro 服务运行。例如若将 fullStaging 列入 debuggableVariants，则无法将其发布至应用商店（因缺少预编译包）。

插件底层实现原理​

React Native Gradle 插件负责配置应用构建流程，以实现 React Native 应用的生产环境部署。 该插件也用于第三方库中，用于运行新架构所需的代码生成器。

插件主要功能概览：

  • 为每个非调试变体创建 createBundle<Variant>JsAndAssets 任务，负责调用 bundle、hermesc 和 compose-source-map 命令

  • 根据 react-native 包内 package.json 的版本号，自动配置正确的 com.facebook.react:react-android 和 com.facebook.react:hermes-android 依赖版本

  • 自动配置所需的 Maven 仓库（Maven Central、Google Maven 仓库、JSC 本地 Maven 仓库等），确保所有 Maven 依赖可正常解析

  • 设置 NDK，以便您能够构建使用新架构的应用

  • 配置 buildConfigFields，以便在运行时判断是否启用了 Hermes 或新架构

  • 将 Metro 开发服务器端口设置为 Android 资源，以便应用知道连接哪个端口

  • 当库或应用为新架构使用代码生成器时，调用 React Native Codegen