設定 iOS 和 macOS 的 Flutter Flavor

本指南向您展示如何為 iOS 或 macOS 應用建立 Flutter Flavor。

Flutter Flavor 本質上是一組設定的集合，用於定義特定版本的應用如何構建和執行。例如，Flavor 可以決定與應用特定版本關聯的圖示、應用名稱、API 金鑰、功能開關和日誌級別。

如果您想為 iOS 應用建立 Flutter Flavor，則需要在 Xcode 中進行操作。Xcode 沒有“Flavor”的概念。相反，您需要設定所謂的“Scheme”（方案），並將自定義配置附加到該方案中。

下圖展示了將兩個 Flutter Flavor（staging 和 production）作為 Xcode Scheme，併為其分配自定義 Xcode 配置的示例

以下步驟展示瞭如何為 Flutter iOS 專案配置名為 staging 和 production 的兩個 Xcode Scheme。您也可以透過將所有 iOS 引用替換為 macOS 來使用這些步驟設定 macOS 專案。

為了實現無縫工作流程，我們從一個名為 flavors_example 的新 Flutter 專案開始，但您也可以隨時在現有專案中進行設定。

1. 建立一個名為 flavors_example 的新 Flutter 專案。

   控制檯

   $ flutter create flavors_example
   

   content_copy

2. 開啟 flavors_example 專案 iOS 版本的預設 Xcode 工作區。

   控制檯

   $ cd flavors_example && open ios/Runner.xcworkspace
   

   content_copy

3. 在 Xcode 專案導航器中開啟 flavors_example 專案

   • 開啟專案導航器（View > Navigators > Project）。

   • 在專案導航器頂部，選擇 Runner。

4. 在 Xcode 中建立 Scheme

   • 開啟 New Scheme 視窗（Product > Scheme > New Scheme）。

   • 在 Target 欄位中，選擇 Runner。

   • 在 Name 框中，輸入 staging。

   • 點選 Okay 新增新 Scheme。

   • 對名為 production 的 Scheme 重複上述步驟。

   • 完成後，檢查以確保您擁有以下 Scheme

     

5. 在 Xcode 中為 Scheme 建立配置

   • 在專案導航器中，選擇 Runner。

   • 在主視窗的 PROJECT 下，選擇 Runner。

   • 如果尚未開啟，請開啟 Info 選項卡。

   • 轉到 Configurations 部分並新增新的 Debug 配置。

     • 點選 +，選擇 Duplicate "Debug" configuration，並將新配置命名為 Debug-staging。
     • 點選 +，選擇 Duplicate "Debug" configuration，並將新配置命名為 Debug-production。

   • 對 Release 配置和 Profile 配置重複上述步驟。

   • 完成後，檢查以確保您擁有以下配置

     

6. 在 Xcode 中將配置分配給 Scheme

   • 開啟 Manage Schemes 視窗（Product > Scheme > Manage Schemes）。

   • 選擇 staging Scheme 並對其進行編輯。

   • 在以下選項卡中，按如下方式更新 Build Configuration 欄位

     • Run: Debug-staging
     • Test: Debug-staging
     • Profile: Profile-staging
     • Analyze: Debug-staging
     • Archive: Release-staging

   • 點選 Close。

   • 對 production Scheme 重複上述步驟。

7. 如果您正在處理包含至少一個 Podfile 的現有 Flutter 專案，請對其進行更新。有關更多資訊，請參閱 更新 Podfile。

8. 為確保一切設定正確，請在 Xcode 中使用新 Scheme 執行您的應用。由於配置設定尚未更改，您不會看到任何視覺差異，但您需要確認應用可以執行。

   • 選擇 staging Scheme（Product > Schemes > staging）。

   • 在工具欄中 staging 的右側，選擇您要測試的 iOS 裝置。在下例中，裝置是 iPhone 16 Pro。

     

   • 執行應用 Scheme（Product > Run）。

   • 對 production Scheme 重複上述步驟。

9. 如果應用執行正常，您就可以開始自定義配置了。有關更多資訊，請參閱 自定義配置。

在 Xcode 中為 iOS 應用建立 Scheme 後，您可以透過 Xcode 或 Flutter 啟動特定 Scheme。您也可以透過將所有 iOS 引用替換為 macOS 來使用這些步驟啟動 macOS 專案。

您可以使用以下步驟透過 Flutter CLI 在 Debug 模式下啟動 Xcode Scheme

1. 在您的 IDE 中，啟動 iOS 模擬器。

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

   控制檯

   $ flutter run --flavor <xcode_scheme_name>
   

   content_copy
   • <xcode_scheme_name>：將其替換為您的 Xcode Scheme 名稱（例如 staging 或 production）。

   示例

   控制檯

   $ flutter run --flavor staging
   

   content_copy

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

   dart

   import 'package:flutter/services.dart';
   

   content_copy

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

   dart

   void main() {
     // appFlavor will match the name of the Xcode scheme
     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

您可以使用以下步驟在 Xcode 中啟動特定 Scheme

1. 選擇您要測試的 Scheme（Product > Schemes > Choose scheme）。

2. 在工具欄的 Scheme 名稱旁邊，選擇您要測試的裝置。

3. 執行應用的 Scheme（Product > Run）。

新增 Xcode Scheme 後，您可以為 iOS 應用自定義它們。您也可以透過將所有 iOS 引用替換為 macOS 來使用這些步驟配置 macOS 專案。

如果您有多個 Scheme，清晰的應用名稱可以快速識別已部署的應用正在使用哪個 Scheme。

以下步驟展示瞭如何在名為 flavors_example 的專案中，為兩個名為 staging 和 production 的 Scheme 新增不同的應用顯示名稱。

1. 在 Xcode 中建立使用者自定義設定

   • 開啟專案導航器（View > Navigators > Project）。

   • 在專案導航器頂部，選擇 Runner。

   • 在主視窗的 TARGETS 下，選擇 Runner。

   • 開啟 Build Settings 選項卡。

   • 在 Basic 選項卡左側，點選 + 並選擇 Add User-Defined Setting。

   • 建立一個名為 APP_DISPLAY_NAME 的設定。

   • 展開 APP_DISPLAY_NAME 設定。

   • 為以下鍵分配對應的值

     • Debug-production: Flavors prod
     • Debug-staging: Flavors staging
     • Profile-production: Flavors prod
     • Profile-staging: Flavors staging
     • Release-production: Flavors prod
     • Release-staging: Flavors staging

2. 在 Xcode 中更新 Info.plist

   • 在專案導航器中，選擇 Runner > Runner > Info 以開啟 flavor_test/ios/Runner/Info.plist。

   • 在 Information Property List 下，找到以下鍵並更新其值

     • Key: CFBundleDisplayName
     • Value: $(APP_DISPLAY_NAME)

3. 啟動每個 Scheme（staging, production）的應用，並確認每個 Scheme 的應用顯示名稱均已更改。要啟動 Scheme，請參閱 啟動 Xcode Scheme 中的步驟。

如果您有多個 Scheme，每個配置使用不同的圖示可以幫助您快速識別已部署的應用正在使用哪個 Scheme。

以下步驟展示瞭如何在名為 flavors_example 的 iOS 專案中，為兩個名為 staging 和 production 的 Scheme 新增不同的圖示。

1. 準備您的圖示

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

   • 生成所需尺寸的 staging 和 production 圖示版本。儲存為 PNG 格式。

2. 將圖示新增到您的 Xcode 專案

   • 開啟專案導航器（View > Navigators > Project）。

   • 在專案導航器中，選擇 Runner > Runner > Assets 以開啟 Assets 視窗。

   • 針對 staging 圖示完成以下步驟

     • 點選 + > iOS > iOS App icon。

     • 將圖示命名為 AppIcon-staging。

     • 將您的 staging 圖示拖入 AppIcon-staging 視窗，並確保圖示已分配到正確的尺寸。

   • 對 production 圖示重複上述步驟。

3. 將圖示連線到您的 Scheme

   • 開啟專案導航器。

   • 在主視窗的 TARGETS 下，選擇 Runner。

   • 如果尚未開啟，請開啟 General 選項卡。

   • 轉到 App Icons and Launch Screen 部分並將其展開。

   • 在 App icon 欄位右側，點選 + 並按如下方式更新欄位

     • Debug-staging: AppIcon-staging
     • Profile-staging: AppIcon-staging
     • Release-staging: AppIcon-staging
     • Debug-production: AppIcon-production
     • Profile-production: AppIcon-production
     • Release-production: AppIcon-production

4. 啟動每個 Scheme（staging, production）的應用，並確認每個 Scheme 的應用圖示均已更改。要啟動 Scheme，請參閱 啟動 Xcode Scheme 中的步驟。

Bundle Identifier 是您應用在 Apple 平臺上的唯一識別符號。如果您將多個 Xcode Scheme 用作 Flutter Flavor，則可以讓 Apple 將每個 Scheme 視為單獨的應用。為此，您需要為每個 Scheme 分配不同的 Bundle Identifier。這使您可以在一個版本的應用中（例如 staging）測試新功能或錯誤修復，而不會影響另一個版本的應用（例如 production）。

以下步驟展示瞭如何在名為 flavors_example 的 iOS 專案中，為兩個名為 staging 和 production 的 Xcode Scheme 設定唯一的 Bundle Identifier。

1. 在 Xcode 中開啟專案導航器（View > Navigators > Project）。

2. 在主視窗的 TARGETS 下，選擇 Runner。

3. 開啟 Build Settings 選項卡。

4. 導航到 Packaging 部分。

5. 展開 Product Bundle Identifier 設定以檢視不同的構建配置。

6. 為每個 Scheme 的構建配置設定所需的 Bundle Identifier。例如

   • Debug-staging, Profile-staging, Release-staging

     com.example.flavorsExample.staging

   • Debug, Profile, Release, Debug-production, Profile-production, Release-production

     com.example.flavorsExample

7. 確保這些 Bundle Identifier 已包含在您的 App ID 中，並且您的 App ID 已在 Apple 開發者賬戶中註冊。

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

如果您正在為 Flutter iOS 專案建立新的 Xcode Scheme，且現有 Flutter 專案中已有 iOS Podfile，則必須更新該 Flutter iOS Podfile 以匹配您在 Xcode 中所做的更改。

以下步驟展示瞭如何在名為 flavors_example 的 Flutter 專案中更新 iOS Podfile，以包含名為 staging 和 production 的兩個新 Xcode Scheme。您也可以透過將所有 iOS 引用替換為 macOS 來使用這些步驟更新 macOS 專案。

1. 在您的 IDE 中，開啟 ios/Podfile 檔案。

2. 進行以下更新並儲存更改。

   flavors_example/ios/Podfile

   ruby

   project 'Runner', {
     ...
     'Debug' => :debug,
     'Debug-staging' => :debug,
     'Debug-production' => :debug,
     'Profile' => :release,
     'Profile-staging' => :release,
     'Profile-production' => :release,
     'Release' => :release,
     'Release-staging' => :release,
     'Release-production' => :release,
     ...
   

   content_copy

您可以使用 構建設定 來管理從編譯、連結到除錯、分發在內的 iOS 構建過程。將構建設定與 Flutter Flavor 結合使用的一種方法是將這些構建設定分配給 Xcode 構建配置。例如，您可能希望為 Debug-staging 和 Debug-production 分配不同的 API URL。例如

# Debug-staging build settings
API_BASE_URL = staging.flavors.com/api

# Debug-production build settings
API_BASE_URL = flavors.com/api

如果您想為特定構建配置新增額外的構建設定，請參閱 Apple 的 將構建配置檔案新增到您的專案。

本文件包含了一些常見的 Xcode Scheme 配置，但您可以應用更多配置。要了解它們，請參閱 自定義專案的構建 Scheme。

有關建立和使用 Flavor 的更多資訊，請查閱以下資源

• 如何使用 FlutterFire CLI 設定多 Flavor 的 Flutter 和 Firebase
• Flutter 中的構建 Flavor（Android 和 iOS），每個 Flavor 使用不同的 Firebase 專案 (Flutter Ready to Go)