跳至主要内容

React Native Gradle 插件

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

使用插件​

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

使用 npx react-native init 创建的新项目已 **自动配置** 插件。如果您使用此命令创建了应用，则无需执行任何额外步骤来安装它。

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

配置插件​

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

要配置插件，您可以在 android/app/build.gradle 中修改 react 块。

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 文件所在的位置。默认为 ..。您可以按如下方式自定义它。

root = file("../")

reactNativeDir​

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

您可以按如下方式自定义它。

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

codegenDir​

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

您可以按如下方式自定义它。

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

cliFile​

这是 React Native CLI 的入口文件。默认为 ../node_modules/react-native/cli.js。由于插件需要调用 CLI 来捆绑和创建您的应用，因此需要入口文件。

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

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

debuggableVariants​

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

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

列为 debuggableVariants 的变体将不包含捆绑包，因此您需要 Metro 来运行它们。

您可以按如下方式自定义它。

debuggableVariants = ["liteDebug", "prodDebug"]

nodeExecutableAndArgs​

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

nodeExecutableAndArgs = ["node"]

bundleCommand​

这是在为您的应用创建捆绑包时要调用的 bundle 命令的名称。如果您使用 RAM Bundles，这将很有用。默认为 bundle，但可以自定义以添加额外的标志，如下所示。

bundleCommand = "ram-bundle"

bundleConfig​

这是将传递给 bundle --config <file> 的配置文件的路径（如果提供）。默认为空（不会提供配置文件）。有关捆绑配置文件的更多信息，请参阅 CLI 文档。可以按如下方式自定义。

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

bundleAssetName​

这是要生成的捆绑包文件的名称。默认为 index.android.bundle。可以按如下方式自定义。

bundleAssetName = "MyApplication.android.bundle"

entryFile​

用于捆绑包生成的入口文件。默认为搜索 index.android.js 或 index.js。可以按如下方式自定义。

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

extraPackagerArgs​

将传递给 bundle 命令的额外标志列表。可用标志列表在 CLI 文档 中。默认为空。可以按如下方式自定义。

extraPackagerArgs = []

hermesCommand​

hermesc 命令（Hermes 编译器）的路径。React Native 附带捆绑的 Hermes 编译器版本，因此您通常不需要自定义它。插件默认将使用适合您系统的正确编译器。

hermesFlags​

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

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

使用 Flavors 和 Build Variants​

在构建 Android 应用时，您可能希望使用 自定义 Flavors 来拥有从同一项目开始的不同版本的应用。

请参阅 官方 Android 指南 以配置自定义构建类型（如 staging）或自定义 Flavors（如 full、lite 等）。默认情况下，新应用会创建两种构建类型（debug 和 release），并且没有自定义 Flavors。

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

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

apply plugin: "com.facebook.react"

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

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

插件在幕后做了什么？​

React Native Gradle 插件负责配置您的应用程序构建以将 React Native 应用程序交付到生产环境。该插件也用于第三方库中，以运行用于新架构的 代码生成。

以下是插件职责的摘要。

  • 为每个不可调试变体添加 createBundle<Variant>JsAndAssets 任务，该任务负责调用 bundle、hermesc 和 compose-source-map 命令。
  • 设置 com.facebook.react:react-android 和 com.facebook.react:hermes-android 依赖项的正确版本，从 react-native 的 package.json 中读取 React Native 版本。
  • 设置使用所有必要的 Maven 依赖项所需的正确 Maven 存储库（Maven Central、Google Maven Repo、JSC 本地 Maven 存储库等）。
  • 设置 NDK 以便您可以构建使用新架构的应用。
  • 设置 buildConfigFields，以便您可以在运行时知道是否启用了 Hermes 或新架构。
  • 将 Metro DevServer 端口设置为 Android 资源，以便应用知道要连接到哪个端口。
  • 如果库或应用正在使用新架构的代码生成，则调用 React Native 代码生成。