为 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 项目。

   console

   $ flutter create flavors_example
   

   content_copy

2. 为 flavors_example 项目的 iOS 版本打开默认的 Xcode workspace。

   console

   $ cd flavors_example && open ios/Runner.xcworkspace
   

   content_copy

3. 在 Xcode 项目导航器中打开 flavors_example 项目：

   • 打开 project navigator（View > Navigators > Project）。

   • 在 project navigator 顶部选择 Runner。

4. 在 Xcode 中创建 scheme：

   • 打开 New Scheme 窗口（Product > Scheme > New Scheme）。

   • 在 Target 字段中选择 Runner。

   • 在 Name 框中输入 staging。

   • 点击 Okay 添加新 scheme。

   • 对名为 production 的 scheme 重复上述步骤。

   • 完成后，检查确认你已拥有以下 scheme：

     

5. 在 Xcode 中为这些 scheme 创建配置：

   • 在 project navigator 中选择 Runner。

   • 在主窗口的 PROJECT 下选择 Runner。

   • 若 Info tab 未打开，请将其打开。

   • 进入 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 并进行编辑。

   • 在以下各个 tab 中，按如下方式更新 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 目录，并输入以下命令：

   console

   $ flutter run --flavor <xcode_scheme_name>
   

   content_copy

   • <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

appFlavor 的值与你定义的 Xcode scheme 名称一致（如 staging 或 production）。构建时未指定 flavor 则 appFlavor 返回 null。 :::

可按以下步骤在 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 在 Xcode 中添加不同的应用显示名称。

1. 在 Xcode 中创建用户自定义设置：

   • 打开 project navigator（View > Navigators > Project）。

   • 在 project navigator 顶部选择 Runner。

   • 在主窗口的 TARGETS 下选择 Runner。

   • 打开 Build Settings tab。

   • 在 Basic tab 左侧，点击 + 并选择 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 在 Xcode 中添加不同图标。

1. 准备你的图标：

   • 用你喜欢的设计工具设计 staging 图标和 production 图标。

   • 生成你所需尺寸的 staging 图标和 production 图标，并以 PNG 格式保存。

2. 将图标添加到你的 Xcode 项目：

   • 打开 project navigator（View > Navigators > Project）。

   • 在 project navigator 中，选择 Runner > Runner > Assets 以打开 Assets 窗口。

   • 对 staging 图标完成以下步骤：

     • 点击 + > iOS > iOS App icon。

     • 将图标命名为 AppIcon-staging。

     • 将你的 staging 图标拖入 AppIcon-staging 窗口，并确保这些图标已分配到正确的尺寸。

   • 对 production 图标重复上一步骤。

3. 将图标关联到你的 scheme：

   • 打开 project navigator。

   • 在主窗口的 TARGETS 下选择 Runner。

   • 若 General tab 尚未打开，请将其打开。

   • 进入 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 的应用图标都已改变。要启动某个 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 中打开 project navigator（View > Navigators > Project）。

2. 在主窗口的 TARGETS 下选择 Runner。

3. 打开 Build Settings tab。

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 Developer 账号中注册。

若资源仅在应用的特定 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. 在你的 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

可使用 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 的更多信息，请参阅以下资源：

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

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