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
。如果您在 monorepo 中或使用不同的包管理器,您可以根据您的设置调整 reactNativeDir
。
您可以按如下方式自定义它
reactNativeDir = file("../node_modules/react-native")
codegenDir
这是 react-native-codegen
包所在的文件夹。默认值为 ../node_modules/react-native-codegen
。如果您在 monorepo 中或使用不同的包管理器,您可以根据您的设置调整 codegenDir
。
您可以按如下方式自定义它
codegenDir = file("../node_modules/@react-native/codegen")
cliFile
这是 React Native CLI 的入口文件。默认值为 ../node_modules/react-native/cli.js
。入口文件是必需的,因为插件需要调用 CLI 来打包和创建您的应用程序。
如果您在 monorepo 中或使用不同的包管理器,您可以根据您的设置调整 cliFile
。您可以按如下方式自定义它
cliFile = file("../node_modules/react-native/cli.js")
debuggableVariants
这是可调试变体的列表(有关变体的更多上下文,请参阅使用变体)。
默认情况下,插件只将 debug
视为 debuggableVariants
,而 release
则不是。如果您有其他变体(如 staging
、lite
等),您需要相应地调整此设置。
列为 debuggableVariants
的变体将不附带打包的 bundle,因此您需要 Metro 来运行它们。
您可以按如下方式自定义它
debuggableVariants = ["liteDebug", "prodDebug"]
nodeExecutableAndArgs
这是所有脚本应调用的 node 命令和参数的列表。默认值为 [node]
,但可以自定义以添加额外标志,如下所示
nodeExecutableAndArgs = ["node"]
bundleCommand
这是为您的应用程序创建 bundle 时要调用的 bundle
命令的名称。如果您使用RAM Bundles,这会很有用。默认值为 bundle
,但可以自定义以添加额外标志,如下所示
bundleCommand = "ram-bundle"
bundleConfig
这是将传递给 bundle --config <file>
的配置文件路径(如果提供)。默认值为空(不提供配置文件)。有关打包配置文件的更多信息,请参阅CLI 文档。可以按如下方式自定义
bundleConfig = file(../rn-cli.config.js)
bundleAssetName
这是要生成的 bundle 文件的名称。默认值为 index.android.bundle
。可以按如下方式自定义
bundleAssetName = "MyApplication.android.bundle"
entryFile
用于 bundle 生成的入口文件。默认是搜索 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"]
enableBundleCompression
捆绑资产在打包成 .apk
时是否应该被压缩。
禁用 .bundle
的压缩允许它直接内存映射到 RAM,从而提高启动时间——代价是磁盘上生成的应用程序大小更大。请注意,.apk
下载大小基本不受影响,因为 .apk
文件在下载前会被压缩。
默认情况下,此功能是禁用的,除非您非常关心应用程序的磁盘空间,否则不应启用它。
使用风格与构建变体
构建 Android 应用时,您可能希望使用自定义风格,以便从同一个项目生成不同版本的应用。
请参阅官方 Android 指南以配置自定义构建类型(如 staging
)或自定义风格(如 full
、lite
等)。默认情况下,新应用会创建两种构建类型(debug
和 release
),并且没有自定义风格。
所有构建类型和所有风格的组合会生成一组构建变体。例如,对于 debug
/staging
/release
构建类型和 full
/lite
,您将有 6 个构建变体:fullDebug
、fullStaging
、fullRelease
等。
如果您使用 debug
和 release
以外的自定义变体,您需要使用debuggableVariants
配置来指示 React Native Gradle 插件哪些变体是可调试的,如下所示
apply plugin: "com.facebook.react"
react {
+ debuggableVariants = ["fullStaging", "fullDebug"]
}
这是必要的,因为插件将跳过所有 debuggableVariants
的 JS 打包:您将需要 Metro 来运行它们。例如,如果您将 fullStaging
列在 debuggableVariants
中,您将无法将其发布到商店,因为它将缺少 bundle。
插件在底层做了什么?
React Native Gradle 插件负责配置您的应用程序构建,以将 React Native 应用程序发布到生产环境。该插件也用于第三方库中,以运行用于新架构的代码生成器(Codegen)。
以下是插件职责的摘要
- 为每个不可调试的变体添加一个
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 Central、Google Maven Repo、JSC local Maven repo 等),以使用所有必要的 Maven 依赖项。
- 设置 NDK,以便您可以使用新架构构建应用程序。
- 设置
buildConfigFields
,以便您可以在运行时知道 Hermes 或新架构是否已启用。 - 将 Metro 开发服务器端口设置为 Android 资源,以便应用程序知道连接到哪个端口。
- 如果库或应用程序使用新架构的代码生成器,则调用React Native 代码生成器。