Skip to main content

React Native Gradle 插件

本指南介绍了在构建适用于 Android 的 React Native 应用时如何配置 React Native Gradle 插件（通常称为 RNGP）。

¥This guide describes how to configure the React Native Gradle Plugin (often referred as RNGP), when building your React Native application for Android.

使用插件​

¥Using the plugin

React Native Gradle 插件作为单独的 NPM 包分发，随 react-native 自动安装。

¥The React Native Gradle Plugin is distributed as a separate NPM package which is installed automatically with react-native.

该插件已针对使用 npx react-native init 创建的新项目进行了配置。如果你使用此命令创建应用，则不需要执行任何额外的步骤来安装它。

¥The plugin is already configured for new projects created using npx react-native init. You don't need to do any extra steps to install it if you created your app with this command.

如果你要将 React Native 集成到现有项目中，请参考 对应的页面：它包含有关如何安装插件的具体说明。

¥If you're integrating React Native into an existing project, please refer to the corresponding page: it contains specific instructions on how to install the plugin.

配置插件​

¥Configuring the plugin

默认情况下，该插件将使用合理的默认值开箱即用。你应该参考本指南并仅在需要时自定义行为。

¥By default, the plugin will work out of the box with sensible defaults. You should refer to this guide and customize the behavior only if you need it.

要配置插件，你可以修改 android/app/build.gradle 内的 react 块：

¥To configure the plugin you can modify the react block, inside your android/app/build.gradle:

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

每个配置键描述如下：

¥Each configuration key is described below:

root​

这是 React Native 项目的根文件夹，即 package.json 文件所在的位置。默认为 ..。你可以按如下方式自定义它：

¥This is the root folder of your React Native project, i.e. where the package.json file lives. Default is ... You can customize it as follows:

root = file("../")

reactNativeDir​

这是 react-native 包所在的文件夹。默认为 ../node_modules/react-native。如果你在 monorepo 中或使用不同的包管理器，则可以使用 adjustment reactNativeDir 来调整你的设置。

¥This is the folder where the react-native package lives. Default is ../node_modules/react-native. If you're in a monorepo or using a different package manager, you can use adjust reactNativeDir to your setup.

你可以按如下方式自定义它：

¥You can customize it as follows:

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

codegenDir​

这是 react-native-codegen 包所在的文件夹。默认为 ../node_modules/react-native-codegen。如果你在 monorepo 中或使用不同的包管理器，则可以根据你的设置调整 codegenDir。

¥This is the folder where the react-native-codegen package lives. Default is ../node_modules/react-native-codegen. If you're in a monorepo or using a different package manager, you can adjust codegenDir to your setup.

你可以按如下方式自定义它：

¥You can customize it as follows:

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

cliFile​

这是 React Native CLI 的入口点文件。默认为 ../node_modules/react-native/cli.js。需要入口点文件，因为插件需要调用 CLI 来打包和创建应用。

¥This is the entrypoint file for the React Native CLI. Default is ../node_modules/react-native/cli.js. The entrypoint file is needed as the plugin needs to invoke the CLI for bundling and creating your app.

如果你在 monorepo 中或使用不同的包管理器，则可以根据你的设置调整 cliFile。你可以按如下方式自定义它：

¥If you're in a monorepo or using a different package manager, you can adjust cliFile to your setup. You can customize it as follows:

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

debuggableVariants​

这是可调试的变体列表（有关变体的更多上下文，请参阅 使用变体）。

¥This is the list of variants that are debuggable (see using variants for more context on variants).

默认情况下，插件仅将 debug 视为 debuggableVariants，而 release 则不然。如果你有其他变体（如 staging、lite 等），则需要相应调整。

¥By default the plugin is considering as debuggableVariants only debug, while release is not. If you have other variants (like staging, lite, etc.) you'll need to adjust this accordingly.

列为 debuggableVariants 的变体不会随打包包一起提供，因此你需要 Metro 来运行它们。

¥Variants that are listed as debuggableVariants will not come with a shipped bundle, so you'll need Metro to run them.

你可以按如下方式自定义它：

¥You can customize it as follows:

debuggableVariants = ["liteDebug", "prodDebug"]

nodeExecutableAndArgs​

这是应该为所有脚本调用的节点命令和参数的列表。默认情况下是 [node]，但可以自定义添加额外的标志，如下所示：

¥This is the list of node command and arguments that should be invoked for all the scripts. By default is [node] but can be customized to add extra flags as follows:

nodeExecutableAndArgs = ["node"]

bundleCommand​

这是为应用创建打包包时要调用的 bundle 命令的名称。如果你使用 内存打包包，这很有用。默认情况下是 bundle，但可以自定义添加额外的标志，如下所示：

¥This is the name of the bundle command to be invoked when creating the bundle for your app. That's useful if you're using RAM Bundles. By default is bundle but can be customized to add extra flags as follows:

bundleCommand = "ram-bundle"

bundleConfig​

这是将传递给 bundle --config <file>（如果提供）的配置文件的路径。默认为空（禁止使用任何配置文件）。有关打包配置文件的更多信息，请参见 在 CLI 文档上。可定制如下：

¥This is the path to a configuration file that will be passed to bundle --config <file> if provided. Default is empty (no config file will be probided). More information on bundling config files can be found on the CLI documentation. Can be customized as follow:

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

bundleAssetName​

这是应该生成的打包文件的名称。默认为 index.android.bundle。可定制如下：

¥This is the name of the bundle file that should be generated. Default is index.android.bundle. Can be customized as follow:

bundleAssetName = "MyApplication.android.bundle"

entryFile​

用于生成打包包的入口文件。默认搜索 index.android.js 或 index.js。可定制如下：

¥The entry file used for bundle generation. The default is to search for index.android.js or index.js. Can be customized as follow:

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

extraPackagerArgs​

将传递给 bundle 命令的额外标志列表。可用标志列表位于 CLI 文档 中。默认为空。可定制如下：

¥A list of extra flags that will be passed to the bundle command. The list of available flags is in the CLI documentation. Default is empty. Can be customized as follows:

extraPackagerArgs = []

hermesCommand​

hermesc 命令（Hermes 编译器）的路径。React Native 附带了与其打包在一起的 Hermes 编译器版本，因此你通常不需要对其进行自定义。默认情况下，该插件将使用适合你系统的正确编译器。

¥The path to the hermesc command (the Hermes Compiler). React Native comes with a version of the Hermes compiler bundled with it, so you generally won't be needing to customize this. The plugin will use the correct compiler for your system by default.

hermesFlags​

要传递给 hermesc 的标志列表。默认为 ["-O", "-output-source-map"]。你可以按如下方式进行自定义

¥The list of flags to pass to hermesc. By default is ["-O", "-output-source-map"]. You can customize it as follows

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

使用风味和构建变体​

¥Using Flavors & Build Variants

构建 Android 应用时，你可能希望使用 定制口味 从同一项目开始拥有不同版本的应用。

¥When building Android apps, you might want to use custom flavors to have different versions of your app starting from the same project.

请参考 官方安卓指南 配置自定义构建类型（如 staging）或自定义样式（如 full、lite 等）。默认情况下，新应用使用两种构建类型（debug 和 release）创建，没有自定义风格。

¥Please refer to the official Android guide to configure custom build types (like staging) or custom flavors (like full, lite, etc.). By default new apps are created with two build types (debug and release) and no custom flavors.

所有构建类型和所有风格的组合会生成一组构建变体。例如，对于 debug/staging/release 构建类型和 full/lite，你将有 6 个构建变体：fullDebug、fullStaging、fullRelease 等。

¥The combination of all the build types and all the flavors generates a set of build variants. For instance for debug/staging/release build types and full/lite you will have 6 build variants: fullDebug, fullStaging, fullRelease and so on.

如果你使用 debug 和 release 之外的自定义变体，则需要指示 React Native Gradle 插件指定哪些变体可以使用 debuggableVariants 配置进行调试，如下所示：

¥If you're using custom variants beyond debug and release, you need to instruct the React Native Gradle Plugin specifying which of your variants are debuggable using the debuggableVariants configuration as follows:

apply plugin: "com.facebook.react"

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

这是必要的，因为插件将跳过所有 debuggableVariants 的 JS 打包：你需要 Metro 来运行它们。例如，如果你在 debuggableVariants 中列出 fullStaging，你将无法将其发布到商店，因为它将丢失打包包。

¥This is necessary because the plugin will skip the JS bundling for all the debuggableVariants: you'll need Metro to run them. For example, if you list fullStaging in the debuggableVariants, you won't be able to publish it to a store as it will be missing the bundle.

该插件在幕后做什么？​

¥What is the plugin doing under the hood?

React Native Gradle 插件负责配置你的应用构建以将 React Native 应用交付到生产环境。该插件还在第 3 方库中使用，以运行用于新架构的 代码生成器。

¥The React Native Gradle Plugin is responsible for configuring your Application build to ship React Native applications to production. The plugin is also used inside 3rd party libraries, to run the Codegen used for the New Architecture.

以下是插件职责的摘要：

¥Here is a summary of the plugin responsibilities:

  • 为每个不可调试的变体添加一个 createBundle<Variant>JsAndAssets 任务，负责调用 bundle、hermesc 和 compose-source-map 命令。

    ¥Add a createBundle<Variant>JsAndAssets task for every non debuggable variant, that is responsible of invoking the bundle, hermesc and compose-source-map commands.

  • 设置正确版本的 com.facebook.react:react-android 和 com.facebook.react:hermes-android 依赖，从 package.json 或 react-native 读取 React Native 版本。

    ¥Setting up the proper version of the com.facebook.react:react-android and com.facebook.react:hermes-android dependency, reading the React Native version from the package.json of react-native.

  • 设置正确的 Maven 存储库（Maven Central、Google Maven Repo、JSC 本地 Maven 存储库等）来使用所有必要的 Maven 依赖。

    ¥Setting up the proper Maven repositories (Maven Central, Google Maven Repo, JSC local Maven repo, etc.) needed to consume all the necessary Maven Dependencies.

  • 设置 NDK 以允许你构建使用新架构的应用。

    ¥Setting up the NDK to let you build apps that are using the New Architecture.

  • 设置 buildConfigFields，以便你可以在运行时知道是否启用了 Hermes 或新架构。

    ¥Setting up the buildConfigFields so that you can know at runtime if Hermes or the New Architecture are enabled.

  • 将 Metro DevServer 端口设置为 Android 资源，以便应用知道要连接哪个端口。

    ¥Setting up the Metro DevServer Port as an Android resource so the app knows on which port to connect.

  • 如果库或应用正在使用新架构的 Codegen，则调用 React Native 代码生成器。

    ¥Invoking the React Native Codegen if a library or app is using the Codegen for the New Architecture.