為 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

2. 開啟 flavors_example 專案的 iOS 版本的預設 Xcode Workspace。

   控制檯

   cd flavors_example && open ios/Runner.xcworkspace

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

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

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

4. 在 Xcode 中建立 Scheme

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

   • 在**Target**欄位中，選擇 **Runner**。

   • 在**Name**框中，輸入 staging。

   • 點選 **Okay** 新增新 Scheme。

   • 為名為 production 的 Scheme 重複之前的步驟。

   • 完成後，請檢查以確保您擁有以下 Schemes：

     

5. 在 Xcode 中為 Schemes 建立配置

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

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

   • 如果**Info 選項卡**未開啟，請將其開啟。

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

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

   • 對於 Release 配置和 Profile 配置，請重複上一步。

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

     

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

   • 開啟**管理 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. 如果您正在處理一個預先存在的 Flutter 專案，其中至少有一個 Podfile，請更新它。有關更多資訊，請參閱更新 Podfile。

8. 為確保您已正確設定所有內容，請在 Xcode 中使用新的 Schemes 執行您的應用。您將看不到任何差異，因為配置設定尚未更改，但您確實想確保應用可以執行。

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

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

     

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

   • 為 production Scheme 重複之前的步驟。

9. 如果一切正常執行，則說明您已準備好自定義配置。有關更多資訊，請參閱自定義配置。

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

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

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

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

   控制檯

   flutter run --flavor <xcode_scheme_name>

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

   示例

   控制檯

   flutter run --flavor staging

您可以透過以下步驟啟動 Xcode 中的特定 Scheme：

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

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

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

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

如果您有多個 Schemes，為每個 Scheme 提供一個獨特的應用名稱可以幫助您快速識別所部署的應用正在使用哪個 Scheme。

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

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，請參閱啟動 Xcode Scheme中的步驟。

如果您有多個 Schemes，為每個配置設定一個獨特的圖示可以幫助您快速識別所部署的應用正在使用哪個 Scheme。

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

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. 將圖示連線到您的 Schemes

   • 開啟**專案導航器**。

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

   • 如果**General**選項卡未開啟，請將其開啟。

   • 轉到**Apps 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，請參閱啟動 Xcode Scheme中的步驟。

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

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

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

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

3. 開啟**Build Settings**選項卡。

4. 導航到**Packaging**部分。

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

6. 對於每個 Scheme 的構建配置，設定所需的 Bundle ID。例如：

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

     com.example.flavorsExample.staging

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

     com.example.flavorsExample

7. 確保這些 Bundle ID 已包含在您的 App ID 中，並且您的 App ID 已在您的 Apple Developer 帳戶中註冊。

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

如果您正在為 Flutter iOS 專案建立新的 Xcode Schemes，並且在現有的 Flutter 專案中有一個 iOS Podfile，您必須更新 Flutter iOS Podfile 以匹配您在 Xcode 中所做的更改。

以下步驟展示瞭如何更新您的 iOS Podfile，以便在名為 flavors_example 的 Flutter 專案中包含兩個新的 Xcode Schemes：staging 和 production。您也可以透過將對 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,
     ...

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

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

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

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

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

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

• 如何使用 FlutterFire CLI 設定具有多個 Flavor 的 Flutter & Firebase
• 在 Flutter 中構建具有不同 Firebase 專案的 Flavor（Android 和 iOS） Flutter Ready to Go