跳到主要內容

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 則否。如果您有其他變體（例如 staging、lite 等），則需要相應地調整此設定。

列為 debuggableVariants 的變體不會隨附已發佈的捆綁包，因此您需要 Metro 才能執行它們。

您可以依照以下方式自訂它

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

nodeExecutableAndArgs​

這是應該為所有腳本調用的節點命令和引數清單。預設值為 [node]，但可以自訂以新增額外標誌，如下所示

groovy
nodeExecutableAndArgs = ["node"]

bundleCommand​

這是用於在為您的應用程式建立捆綁包時調用的 bundle 命令名稱。如果您使用RAM 捆綁包，這會很有用。預設值為 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​

hermesc 命令（Hermes 編譯器）的路徑。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，則需要指示 React Native Gradle 外掛程式，使用debuggableVariants 設定指定您的哪些變體是可偵錯的，如下所示

diff
apply plugin: "com.facebook.react"

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

這是必要的，因為此外掛程式將跳過所有 debuggableVariants 的 JS 捆綁：您需要 Metro 才能執行它們。例如，如果您在 debuggableVariants 中列出 fullStaging，則您將無法將其發佈到商店，因為它將缺少捆綁包。

此外掛程式在底層執行什麼操作？​

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 本地 Maven 儲存庫等），以使用所有必要的 Maven 依賴項。
  • 設定 NDK，讓您可以建置使用新架構的應用程式。
  • 設定 buildConfigFields，以便您可以在執行階段知道是否已啟用 Hermes 或新架構。
  • 將 Metro DevServer 連接埠設定為 Android 資源，以便應用程式知道要連接到哪個連接埠。
  • 如果函式庫或應用程式使用新架構的 Codegen，則調用 React Native Codegen。