為 Android 設定 Flutter flavors

本指南將說明如何為 Android 應用程式建立 Flutter flavors。

在 Android 中，Flutter flavor 代表一個統一的術語，涵蓋多種平台專屬功能。例如，flavor 可以決定特定版本的應用程式所使用的圖示、應用程式名稱、API 金鑰、功能旗標（feature flag）以及日誌等級。

如果你想為 Android 應用程式建立 Flutter flavors，可以直接在 Flutter 中進行。在 Android 裡，Flutter flavor 被稱為 product flavor。

以下範例說明當一個 Android 應用程式擁有兩個 product flavors（staging、production）以及兩個 build types（debug、release）時，所產生的 Android build variants：

請依照以下步驟，將兩個名為 staging 和 production 的 Android product flavors 新增到一個名為 flavors_example 的 Flutter 新專案中，並測試專案以確保 flavors 運作正常。

1. 建立一個名為 flavors_example 的 Flutter 新專案，並選擇 Kotlin 作為 Android 首選語言。預設情況下，該專案會包含 debug 和 release 這兩種 Android build types。

   console

   flutter create --android-language kotlin flavors_example

2. 在 flavors_example 專案中新增名為 staging 和 production 的 product flavors。

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

   • 在 android {} block 內新增 flavorsDimension 屬性以及 productFlavors 屬性。請確保 android {} 區塊同時包含預設的 debug 和 release build types：

     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"
             }
         }
     }

3. 為了確保你已正確完成所有設定，請在 Android 的產品風味（product flavors）上執行你的應用程式。雖然目前設定尚未變更，所以你不會看到任何差異，但你仍然需要確認應用程式可以正常運作。

   • 啟動 Android 模擬器，或連接已啟用開發人員選項的實體裝置。

   • 在終端機中，切換到 flavors_example 目錄，然後輸入以下指令來測試 staging 風味（flavor）：

     console

     flutter run --flavor staging

   • 針對production flavor，重複前一個步驟。

4. 如果一切運作正常，您就可以開始自訂您的設定了。欲了解更多資訊，請參閱 Customize configurations。

在您為 Android 應用程式建立好 product flavors 之後，可以透過 Flutter 啟動特定的 product flavor。

您可以依照以下步驟，使用 Flutter 命令列介面 (Command Line Interface) 啟動指定的 product flavor：

1. 啟動 Android 模擬器，或連接已啟用開發人員選項的實體裝置。

2. 在終端機中，切換到flavors_example目錄，並輸入以下指令：

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

• (run | build <subcommand>)：請以以下其中一項取代：

  • run：以偵錯模式（debug mode）執行應用程式。
  • build：建置 APK 或 appbundle。
    • <subcommand>：可為 apk 或 appbundle。

• <flavor_name>：請以您的 Android 產品 flavor 名稱取代（例如：staging、production）。

範例：

flutter build apk --flavor staging

在你加入產品風味（product flavors）後，可以針對你的 Android 應用程式進行自訂設定。

如果你有多個產品風味，獨特的應用程式名稱可以讓你快速辨識部署的應用程式所使用的風味。

以下步驟說明如何為一個名為 flavors_example 的專案中的兩個產品風味 staging 和 production，分別加入獨特的應用程式顯示名稱。

1. 在你的 IDE 中更新 build.gradle.kts：

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

   • 在 flavorsDimension 區塊中，於 staging 和 production 這兩個風味下，新增一個名為 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"
             }
         }

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"
           ...
         />
     />

3. 針對每個產品 flavor（staging、production）啟動應用程式，並檢查每個 flavor 的應用程式顯示名稱是否有變更。

   • 如需啟動特定產品 flavor，請參考啟動 flavor的步驟。

   • 在 Android App 模擬器中，前往應用程式清單。你應該會看到Flavors p...和Flavors s...各自的應用程式。

   • 若要查看更多Flavors p...或Flavors s...的資訊，請長按其中一個圖示，然後選擇App info。

如果你有多個產品 flavor，為每個組態設計專屬圖示可以幫助你快速辨識目前部署的應用程式所使用的 flavor。

以下步驟說明如何在名為flavors_example的專案中，為兩個名為staging和production的產品 flavor 新增專屬圖示。

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 的資源（assets），你可以設定它們僅在啟動該 flavor 時才會被打包進應用程式。這樣可以避免未使用的資源使你的應用程式包體變大。若要為每個 flavor 打包資源，請在專案的 pubspec 中的assets欄位下新增flavors子欄位。欲了解更多資訊，請參閱 assets 欄位於Flutter pubspec options。

你可以讓應用程式在未指定 flavor 時，預設使用特定 flavor。為此，請在專案的 pubspec 中新增default-flavor欄位。欲了解更多資訊，請參閱 default-flavor 欄位於Flutter pubspec options。

如果你想為特定 Android 產品 flavor 設定額外的建置選項，請參閱 Android 的設定建置變體。

如需建立與使用 flavor 的更多資訊，請參考以下資源：

• 在 Flutter（Android 和 iOS）中使用 Firebase 建立 Build flavors
• 如何使用 FlutterFire CLI 設定 Flutter & Firebase 多個 Flavors