跳到主要内容

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 代码块。

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 则不是。如果你有其他变体(例如 staginglite 等),你需要相应地调整此设置。

列为 debuggableVariants 的变体不会附带已打包的 bundle,因此你需要 Metro 才能运行它们。

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

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

nodeExecutableAndArgs

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

groovy
nodeExecutableAndArgs = ["node"]

bundleCommand

这是在为你的应用创建 bundle 时要调用的 bundle 命令的名称。如果你正在使用 RAM Bundles,这将非常有用。默认值为 bundle,但可以自定义以添加额外的标志,如下所示

groovy
bundleCommand = "ram-bundle"

bundleConfig

这是配置文件的路径,如果提供,该文件将传递给 bundle --config <file>。默认值为空(不提供配置文件)。有关打包配置文件的更多信息,请参阅 CLI 文档。可以按如下方式自定义

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

bundleAssetName

这是应该生成的 bundle 文件的名称。默认值为 index.android.bundle。可以按如下方式自定义

groovy
bundleAssetName = "MyApplication.android.bundle"

entryFile

用于生成 bundle 的入口文件。默认值是搜索 index.android.jsindex.js。可以按如下方式自定义

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

extraPackagerArgs

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

groovy
extraPackagerArgs = []

hermesCommand

hermesc 命令(Hermes 编译器)的路径。React Native 自带一个 Hermes 编译器版本,因此你通常不需要自定义此项。默认情况下,插件将为你的系统使用正确的编译器。

hermesFlags

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

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

enableBundleCompression

Bundle Asset 在打包到 .apk 中时是否应压缩。

禁用 .bundle 的压缩允许它直接内存映射到 RAM,从而缩短启动时间 - 但代价是磁盘上生成的应用尺寸更大。请注意,.apk 下载大小将基本不受影响,因为 .apk 文件在下载前已压缩

默认情况下,此项已禁用,除非你真的非常关心应用程序的磁盘空间,否则你不应启用它。

使用 Flavors & 构建变体

在构建 Android 应用时,你可能希望使用 自定义 flavors,以便从同一项目开始拥有不同版本的应用。

请参阅 Android 官方指南 来配置自定义构建类型(如 staging)或自定义 flavors(如 fulllite 等)。默认情况下,新应用使用两种构建类型(debugrelease)创建,并且没有自定义 flavors。

所有构建类型和所有 flavors 的组合会生成一组构建变体。例如,对于 debug/staging/release 构建类型和 full/lite flavors,你将有 6 个构建变体:fullDebugfullStagingfullRelease 等。

如果你使用的自定义变体超出 debugrelease,你需要指示 React Native Gradle 插件,使用 debuggableVariants 配置指定哪些变体是可调试的,如下所示

diff
apply plugin: "com.facebook.react"

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

这是必要的,因为插件将跳过所有 debuggableVariants 的 JS 打包:你需要 Metro 才能运行它们。例如,如果你在 debuggableVariants 中列出 fullStaging,你将无法将其发布到商店,因为它会缺少 bundle。

插件在底层做了什么?

React Native Gradle 插件负责配置你的应用程序构建,以便将 React Native 应用程序发布到生产环境。该插件也用于第三方库内部,以运行用于新架构的 代码生成

以下是插件职责的摘要

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