为 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. Create a new Flutter project called flavors_example.

   console

   $ flutter create flavors_example
   

   content_copy

2. Open the default Xcode workspace for the iOS version of the flavors_example project.

   console

   $ cd flavors_example && open ios/Runner.xcworkspace
   

   content_copy

3. Open the flavors_example project in the Xcode project navigator:

   • Open the project navigator (View > Navigators > Project).

   • In the project navigator, at the top, select Runner.

4. Create schemes in Xcode:

   • Open the New Scheme window (Product > Scheme > New Scheme).

   • In the Target field, select Runner.

   • In the Name box, enter staging.

   • Click Okay to add the new scheme.

   • Repeat the previous steps for a scheme called production.

   • When finished, check to make sure that you have the following schemes:

     

5. Create configurations for the schemes in Xcode:

   • In the project navigator, select Runner.

   • In the main window under PROJECT, select Runner.

   • Open the Info tab if it isn’t open.

   • Go to the Configurations section and add new Debug configurations.

     • Click +, select Duplicate "Debug" configuration, and name the new configuration Debug-staging.
     • Click +, select Duplicate "Debug" configuration, and name the new configuration Debug-production.

   • Repeat the previous step for the Release configurations and the Profile configurations.

   • When finished, check to make sure that you have the following configurations:

     

6. Assign the configurations to the schemes in Xcode:

   • Open the Manage Schemes window (Product > Scheme > Manage Schemes).

   • Select the staging scheme and edit it.

   • In the following tabs, update the Build Configuration field as follows:

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

   • Click Close.

   • Repeat the previous steps for the production scheme.

7. If you are working with a pre-existing Flutter project that has at least one Podfile, update it. For more information, see Update Podfiles.

8. To make sure that you've set up everything correctly, run your app on the new schemes in Xcode. You won't see any differences because the configuration settings haven't changed, but you do want to make sure that the app can run.

   • Select the staging scheme (Product > Schemes > staging).

   • To the right of staging in the toolbar, select the iOS device you want to test against. In the following example, the device is iPhone 16 Pro.

     

   • Run the app scheme (Product > Run).

   • Repeat the previous steps for the production scheme.

9. If everything runs, you're ready to customize your configurations. For more information, see Customize configurations.

在 Xcode 中为 iOS 应用创建 scheme 后，可通过 Xcode 或 Flutter 启动特定 scheme。将 iOS 替换为 macOS 也可用于 macOS 项目。

可使用 Flutter CLI 按以下步骤以 Debug 模式启动 Xcode scheme：

1. 在 IDE 中启动 iOS 模拟器。

2. 在控制台中进入 flavors_example 目录，并输入以下命令：

   console

   $ flutter run --flavor <xcode_scheme_name>
   

   content_copy

   • <xcode_scheme_name>: Replace this with the name of your Xcode scheme (for example, staging or production).

   • <xcode_scheme_name>：替换为你的 Xcode scheme 名称（例如 staging 或 production）。

   示例：

   console

   $ flutter run --flavor staging
   

   content_copy

1. 导入 services 库： 要访问 appFlavor 常量，在 Dart 文件中添加以下 import：

   dart

   import 'package:flutter/services.dart';
   

   content_copy

2. 检查 flavor 值： 在应用逻辑（通常在 main() 中）使用 appFlavor 常量处理 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. Select the scheme you want to test (Product > Schemes > Choose scheme).

2. Next to the scheme name in the toolbar, select the device you want to test against.

3. Run the scheme for your app (Product > Run).

添加 Xcode scheme 后，可为 iOS 应用自定义。将 iOS 替换为 macOS 也可配置 macOS 项目。

若有多个 scheme，不同的应用名称可快速识别已部署应用使用的 scheme。

以下步骤说明如何在名为 flavors_example 的项目中，为 staging 和 production 两个 scheme 在 Xcode 中添加不同的应用显示名称。

1. Create user-defined settings in Xcode:

   • Open the project navigator (View > Navigators > Project).

   • In the project navigator, at the top, select Runner.

   • In the main window under TARGETS, select Runner.

   • Open the Build Settings tab.

   • To the left of the Basic tab, click + and select Add User-Defined Setting.

   • Create a setting named APP_DISPLAY_NAME.

   • Expand the APP_DISPLAY_NAME setting.

   • Assign the following values to the following keys:

     • 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. Update Info.plist in Xcode:

   • In the project navigator, select Runner > Runner > Info to open flavor_test/ios/Runner/Info.plist.

   • Under Information Property List, find the following key and update the value for it:

     • Key: CFBundleDisplayName
     • Value: $(APP_DISPLAY_NAME)

3. Launch the app for each scheme (staging, production) and check to make sure that the app display name has changed for each. To launch a scheme, see the steps in Launch an Xcode scheme.

若有多个 scheme，为各配置使用不同图标有助于快速识别已部署应用使用的 scheme。

以下步骤说明如何在名为 flavors_example 的 iOS 项目中，为 staging 和 production 两个 scheme 在 Xcode 中添加不同图标。

1. Prepare your icons:

   • Design your staging icon and production icon in the design tool of your choice.

   • Generate versions of the staging icon and production icon in the sizes that you need. Save them in PNG format.

2. Add the icons to your Xcode project:

   • Open the project navigator (View > Navigators > Project).

   • In the project navigator, select Runner > Runner > Assets to open the Assets window.

   • Complete the following steps for the staging icon:

     • Click + > iOS > iOS App icon.

     • Name the icon AppIcon-staging.

     • Drag your staging icons into the AppIcon-staging window and make sure the icons are assigned to the correct sizes.

   • Repeat the previous step for the production icon.

3. Connect the icons to your schemes:

   • Open the project navigator.

   • In the main window under TARGETS, select Runner.

   • Open the General tab if it's not already open.

   • Go to the Apps Icons and Launch Screen section and expand it.

   • To the right of the App icon field, click + and update the fields as follows:

     • 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. Launch the app for each scheme (staging, production) and check to make sure that the app icon has changed for each. To launch a scheme, see the steps in Launch an 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. In Xcode, open the project navigator (View > Navigators > Project).

2. In the main window under TARGETS, select Runner.

3. Open the Build Settings tab.

4. Navigate to the Packaging section.

5. Expand the Product Bundle Identifier setting to see the different build configurations.

6. For each scheme's build configuration, set the desired bundle identifier. For example:

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

     com.example.flavorsExample.staging

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

     com.example.flavorsExample

7. Ensure that these bundle identifiers are included in your App ID and your App ID is registered in your Apple Developer account.

若资源仅在应用的特定 flavor 中使用，可配置为仅在该 flavor 启动时打包，避免未使用资源增大包体积。为每个 flavor 打包资源，请在项目 pubspec 的 assets 字段添加 flavors 子字段。详见 Flutter pubspec options 中的 assets field。

若为 Flutter iOS 项目创建新 Xcode scheme 且现有 Flutter 项目有 iOS Podfile，必须更新 Flutter iOS Podfile 以匹配 Xcode 中的更改。

以下步骤说明如何在名为 flavors_example 的 Flutter 项目中更新 iOS Podfile 以包含 staging 和 production 两个新 Xcode scheme。将 iOS 替换为 macOS 也可用于 macOS 项目。

1. In your IDE, open the ios/Podfile file.

2. Make the following updates and save your changes.

   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

可使用 build settings（构建设置）管理从编译、链接到调试和分发的 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 的 Adding a build configuration file to your project（向项目添加构建配置文件）。

本文档包含若干常见 Xcode scheme 配置，还可应用更多配置。详见 Customizing the build schemes for a project（自定义项目的构建 scheme）。

有关创建和使用 flavor 的更多信息，请参阅以下资源：

• How to set up Flutter & Firebase with Multiple Flavors using the FlutterFire CLI

• 使用 FlutterFire CLI 配置多 Flavor 的 Flutter 与 Firebase

• Build flavors in Flutter (Android and iOS) with different Firebase projects per flavor Flutter Ready to Go

• Flutter 中按 flavor 使用不同 Firebase 项目的构建 flavor（Android 与 iOS）