设置 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)