設定 Android 版 Flutter Flavors

本指南向你展示如何為 Android 應用建立 Flutter Flavor。

當與 Android 一起使用時，Flutter Flavor 是各種平臺特定功能的一個統一術語。例如，Flavor 可以決定與應用特定版本關聯的圖示、應用名稱、API 金鑰、功能標誌 (feature flag) 和日誌級別。

如果你想為 Android 應用建立 Flutter Flavor，可以在 Flutter 中完成。在 Android 中，Flutter Flavor 被稱為 product flavor (產品 Flavor)。

下圖展示了當 Android 應用具有兩個產品 Flavor（staging、production）和兩個構建型別（debug、release）時所建立的 Android 構建變體 (build variants) 的示例：

完成以下步驟，為一個名為 flavors_example 的新 Flutter 專案新增兩個名為 staging 和 production 的 Android 產品 Flavor，然後測試你的專案以確保 Flavor 按預期工作。

1. 建立一個名為 flavors_example 的新 Flutter 專案，並將 Kotlin 作為首選 Android 語言。預設情況下，該專案包含 debug 和 release Android 構建型別。

   控制檯

   $ flutter create --android-language kotlin flavors_example
   

   content_copy

2. 將名為 staging 和 production 的產品 Flavor 新增到 flavors_example 專案中。

   • 在 flavors_example 專案中，導航到 android/app/ 目錄並開啟 build.gradle.kts。

   • 在 android {} 程式碼塊內新增 flavorsDimension 屬性和 productFlavors 屬性。確保 android {} 程式碼塊中也包含預設的 debug 和 release 構建型別。

     build.gradle.kts

     kotlin

     android {
         ...
         buildTypes {
           getByName("debug") {...}
           getByName("release") {...}
         }
         ...
         flavorDimensions += "default"
         productFlavors {
             create("staging") {
                 dimension = "default"
                 applicationIdSuffix = ".staging"
             }
             create("production") {
                 dimension = "default"
                 applicationIdSuffix = ".production"
             }
         }
     }
     

     content_copy

3. 為了確保你已正確設定所有內容，請在 Android 產品 Flavor 上執行你的應用。由於配置設定尚未更改，你不會看到任何差異，但你需要確保應用能夠執行。

   • 啟動 Android 模擬器或連線啟用了開發者選項的物理裝置。

   • 在控制檯中，導航到 flavors_example 目錄並輸入以下命令來測試 staging Flavor：

     控制檯

     $ flutter run --flavor staging
     

     content_copy

   • 對 production Flavor 重複上一步。

4. 如果一切執行正常，你就可以自定義配置了。有關更多資訊，請參閱 自定義配置。

為 Android 應用建立產品 Flavor 後，你可以透過 Flutter 啟動特定的產品 Flavor。

你可以按照以下步驟使用 Flutter CLI 啟動產品 Flavor：

1. 啟動 Android 模擬器或連線啟用了開發者選項的物理裝置。

2. 在控制檯中，導航到 flavors_example 目錄並輸入以下命令：

$ flutter (run | build <subcommand>) --flavor <flavor_name>

• (run | build <subcommand>)：將其替換為以下其中之一：

  • run：在除錯模式下執行應用。
  • build：構建 APK 或 App Bundle。
    • <subcommand>：apk 或 appbundle。

• <flavor_name>：將其替換為你的 Android 產品 Flavor 名稱（例如：staging、production）。

示例

$ flutter build apk --flavor staging

配置完產品 Flavor 後，你可以根據活動的 Flavor 更改應用的行為，例如指向不同的 API 端點或更改主題。

Flutter 框架提供了 appFlavor 常量，它將當前 Flavor 的名稱作為 String 檢索。此值與 flutter run 或 flutter build 過程中傳遞給 --flavor 標誌的 Flavor 名稱匹配。

1. 匯入 services 庫：要訪問 appFlavor 常量，請將以下匯入新增到你的 Dart 檔案中：

   dart

   import 'package:flutter/services.dart';
   

   content_copy

2. 檢查 Flavor 值：在你的應用邏輯（通常在 main() 中）中使用 appFlavor 常量來處理特定於 Flavor 的配置：

   dart

   void main() {
     // appFlavor will match the flavor name from build.gradle.kts
     if (appFlavor == 'production') {
       // Logic for production environment
       Config.apiUrl = 'https://api.flavors_example.com';
     } else if (appFlavor == 'staging') {
       // Logic for staging environment
       Config.apiUrl = 'https://staging.api.flavors_example.com';
     }
   ​
     runApp(const MyApp());
   }
   

   content_copy

新增產品 Flavor 後，你可以為你的 Android 應用自定義它們。

如果你有多個產品 Flavor，不同的應用名稱可以讓你快速識別部署的應用正在使用哪個 Flavor。

以下步驟展示瞭如何為一個名為 flavors_example 的專案中的兩個產品 Flavor（staging 和 production）新增不同的應用顯示名稱。

1. 在 IDE 中更新 build.gradle.kts

   • 在 flavors_example 專案中，導航到 android/app/ 目錄並開啟 build.gradle.kts。

   • 在 flavorsDimension 程式碼塊中，為 staging 和 production Flavor 新增一個名為 app_name 的 resValue() 屬性：

     build.gradle.kts

     kotlin

     android {
         ...
         flavorDimensions += "default"
         productFlavors {
             create("staging") {
                 dimension = "default"
                 resValue(
                     type = "string",
                     name = "app_name",
                     value = "Flavors staging")
                 applicationIdSuffix = ".staging"
             }
             create("production") {
                 dimension = "default"
                 resValue(
                     type = "string",
                     name = "app_name",
                     value = "Flavors production")
                 applicationIdSuffix = ".production"
             }
         }
     

     content_copy

2. 在 IDE 中更新 AndroidManifest.xml

   • 在 flavors_example 專案中，導航到 android/app/src/main 並開啟 AndroidManifest.xml。

   • 將 android:label 的值替換為 @string/app_name。

     AndroidManifest.xml

     xml

     <manifest xmlns:android="http://schemas.android.com/apk/res/android">
         <application
           android:label="@string/app_name"
           ...
         />
     />
     

     content_copy

3. 為每個產品 Flavor（staging、production）啟動應用，並檢查確保每個應用顯示名稱都已更改。

   • 要啟動產品 Flavor，請參閱 啟動 Flavor 中的步驟。

   • 在 Android 應用模擬器中，轉到應用列表。你應該能看到 Flavors p... 和 Flavors s... 的應用。

   • 要檢視 Flavors p... 或 Flavors s... 的更多資訊，請長按其中一個圖示並選擇 App info (應用資訊)。

如果你有多個產品 Flavor，為每個配置設定不同的圖示可以幫助你快速識別部署的應用正在使用哪個 Flavor。

以下步驟展示瞭如何為一個名為 flavors_example 的專案中的兩個產品 Flavor（staging 和 production）新增不同的圖示。

1. 準備你的圖示

   • 在你選擇的設計工具中設計你的 staging 圖示和 production 圖示。

   • 按以下尺寸生成 staging 圖示和 production 圖示的 PNG 版本：

     • mipmap-mdpi (48x48 畫素)
     • mipmap-hdpi (72x72 畫素)
     • mipmap-xhdpi (96x96 畫素)
     • mipmap-xxhdpi (144x144 畫素)
     • mipmap-xxxhdpi (192x192 畫素)

2. 建立特定於 Flavor 的資源目錄

   • 導航到 android/app/src 目錄。

   • 建立一個名為 staging/res 的目錄。

   • 導航到 staging/res 目錄。

   • 建立以下 mipmap 目錄並將 staging 圖示的版本移動到其中：

     • mipmap-mdpi/48x48_staging.png
     • mipmap-hdpi/72x72_staging.png
     • mipmap-xhdpi/96x96_staging.png
     • mipmap-xxhdpi/144x144_staging.png
     • mipmap-xxxhdpi/192x192_staging.png

   • 對 production Flavor 的目錄和圖示重複上述步驟。

   • 將所有圖示重新命名為 ic_launcher.png。

3. 在 IDE 中仔細檢查 AndroidManifest.xml 中的配置

   • 在 flavors_example 專案中，導航到 android/app/src/main 並開啟 AndroidManifest.xml。

   • 確保 android:icon 的值為 @mipmap/ic_launcher。

4. 為每個產品 Flavor（staging、production）啟動應用，並檢查確保每個應用圖示都已更改。要啟動產品 Flavor，請參閱 啟動 Flavor 中的步驟。

如果你的應用中有僅在特定 Flavor 中使用的資源，你可以將它們配置為僅在啟動該 Flavor 時打包進應用。這可以防止你的應用包體積因未使用的資源而增大。要為每個 Flavor 打包資源，請將 flavors 子欄位新增到專案 pubspec 中的 assets 欄位。要了解更多資訊，請參閱 Flutter pubspec 選項 中的 assets 欄位。

你可以在不指定 Flavor 的情況下啟動應用時，讓應用使用特定的 Flavor。為此，你需要將 default-flavor 欄位新增到專案的 pubspec 中。要了解更多資訊，請參閱 Flutter pubspec 選項 中的 default-flavor 欄位。

如果你有其他想要為特定的 Android 產品 Flavor 配置的構建設定，請參閱 Android 的 配置構建變體 (Configure build variants)。

雖然可以在產品 Flavor 中設定 abiFilters，但不建議這樣做。建議在構建型別 (build types) 中設定 abiFilters。在產品 Flavor 中設定 abiFilters 時，執行 flutter build 或 flutter run 時必須使用 -Pdisable-abi-filtering 標誌。

有關建立和使用 Flavor 的更多資訊，請檢視以下資源：

• 使用 Firebase 在 Flutter (Android 和 iOS) 中構建 Flavor
• 如何使用 FlutterFire CLI 設定帶有多個 Flavor 的 Flutter 和 Firebase