为 iOS 和 macOS 设置 Flutter flavors

本指南演示如何为 iOS 或 macOS 应用创建 Flutter flavors。

Flutter flavor 基本上是一组定义应用特定版本应该如何构建和运行的设置。例如，flavor 可以确定与应用特定版本关联的图标、应用名称、API 密钥、功能标志和日志级别。

如果要为 iOS 应用创建 Flutter flavors，则需要在 Xcode 中执行此操作。Xcode 没有称为“flavor”的概念。相反，您需要设置一种称为 scheme 的东西，并为其附加自定义配置。

以下说明了两个 Flutter flavors（staging、production）作为 Xcode schemes，并为其分配了自定义 Xcode 配置

以下步骤说明如何为您的 Flutter iOS 项目配置两个名为 staging 和 production 的 Xcode schemes。您还可以通过将任何对 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 项目

   • 打开 项目导航器 (视图 > 导航器 > 项目)。

   • 在 项目导航器 顶部，选择 Runner。

4. 在 Xcode 中创建 schemes

   • 打开 新建 Scheme 窗口 (产品 > Scheme > 新建 Scheme)。

   • 在 目标 字段中，选择 Runner。

   • 在 名称 框中，输入 staging。

   • 单击 确定 以添加新的 scheme。

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

   • 完成后，检查以确保您拥有以下 schemes

     

5. 在 Xcode 中为 schemes 创建配置

   • 在 项目导航器 中，选择 Runner。

   • 在主窗口的 项目 下方，选择 Runner。

   • 如果未打开，请打开 信息标签。

   • 转到 配置 部分，并添加新的 Debug 配置。

     • 单击 +，选择 复制“Debug”配置，并为新配置命名为 Debug-staging。
     • 单击 +，选择 复制“Debug”配置，并为新配置命名为 Debug-production。

   • 对 Release 配置和 Profile 配置重复上述步骤。

   • 完成后，检查以确保您拥有以下配置

     

6. 在 Xcode 中将配置分配给 schemes

   • 打开 管理 Schemes 窗口 (产品 > Scheme > 管理 Schemes)。

   • 选择 staging scheme 并进行编辑。

   • 在以下选项卡中，更新 构建配置 字段如下

     • 运行: Debug-staging
     • 测试: Debug-staging
     • Profile: Profile-staging
     • 分析: Debug-staging
     • 归档: Release-staging

   • 单击 关闭。

   • 对 production scheme 重复上述步骤。

7. 如果您正在使用至少包含一个 Podfile 的现有 Flutter 项目，请更新它。有关更多信息，请参阅 更新 Podfiles。

8. 为了确保您已正确设置所有内容，请在 Xcode 中使用新的 schemes 运行您的应用。您不会看到任何差异，因为配置设置没有更改，但您需要确保应用可以运行。

   • 选择 staging scheme (产品 > Schemes > staging)。

   • 在工具栏中，在 staging 右侧，选择您要测试的 iOS 设备。在以下示例中，该设备为 iPhone 16 Pro。

     

   • 运行应用 scheme (产品 > 运行)。

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

   content_copy
   • <xcode_scheme_name>: 将其替换为您的 Xcode scheme 名称（例如，staging 或 production）。

   示例

   控制台

   $ flutter run --flavor staging
   

   content_copy

1. 导入 services 库： 要访问 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 (产品 > Schemes > 选择 scheme)。

2. 在工具栏中，在 scheme 名称旁边，选择您要测试的设备。

3. 运行您的应用 scheme (产品 > 运行)。

在 Xcode 中添加 schemes 后，您可以自定义它们以用于您的 iOS 应用。您还可以通过将任何对 iOS 的引用替换为 macOS 来使用这些步骤配置 macOS 项目。

如果您有多个 schemes，则不同的应用名称可以快速识别您部署的应用正在使用哪个 scheme。

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

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

   • 打开 项目导航器 (视图 > 导航器 > 项目)。

   • 在 项目导航器 顶部，选择 Runner。

   • 在主窗口的 目标 下方，选择 Runner。

   • 打开 构建设置 选项卡。

   • 在 Basic 选项卡左侧，单击 + 并选择 添加用户定义的设置。

   • 创建一个名为 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。

   • 在 信息属性列表 下，找到以下键并更新其值

     • 键: CFBundleDisplayName
     • 值: $(APP_DISPLAY_NAME)

3. 为每个 scheme（staging、production）启动应用，并检查应用显示名称是否已更改。有关启动 scheme 的步骤，请参阅 启动 Xcode scheme。

如果您有多个 schemes，则每个配置的不同图标可以帮助您快速识别您部署的应用正在使用哪个 scheme。

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

1. 准备您的图标

   • 在您选择的设计工具中设计您的 staging 图标和 production 图标。

   • 生成 staging 图标和 production 图标的 PNG 格式版本。

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

   • 打开 项目导航器 (视图 > 导航器 > 项目)。

   • 在 项目导航器 中，选择 Runner > Runner > Assets 以打开 Assets 窗口。

   • 完成以下步骤以获取 staging 图标

     • 单击 + > iOS > iOS App icon。

     • 将图标命名为 AppIcon-staging。

     • 将您的 staging 图标拖动到 AppIcon-staging 窗口，并确保图标分配给正确的尺寸。

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

3. 将图标连接到您的 schemes

   • 打开 项目导航器。

   • 在主窗口的 目标 下方，选择 Runner。

   • 打开 常规标签（如果尚未打开）。

   • 转到 应用图标和启动屏幕 部分并展开它。

   • 在 应用图标 字段右侧，单击 + 并更新字段如下

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

捆绑标识符是您在 Apple 平台上应用程序的唯一标识符。如果您正在使用多个 Xcode schemes 作为 Flutter flavors，您可以让 Apple 将每个 scheme 视为一个单独的应用程序。为此，您需要为每个 scheme 分配不同的捆绑标识符。这允许您在一个版本的应用程序（例如 staging）中测试新功能或错误修复，而不会影响另一个版本的应用程序（例如 production）。

以下步骤展示了如何在名为 flavors_example 的 iOS 项目中为两个名为 staging 和 production 的 Xcode schemes 设置唯一的捆绑标识符。

1. 在 Xcode 中，打开 项目导航器（视图 > 导航器 > 项目）。

2. 在主窗口的 目标 下方，选择 Runner。

3. 打开 构建设置 选项卡。

4. 导航到 打包 部分。

5. 展开 产品捆绑标识符 设置以查看不同的构建配置。

6. 为每个 scheme 的构建配置设置所需的捆绑标识符。例如

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

     com.example.flavorsExample.staging

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

     com.example.flavorsExample

7. 确保这些捆绑标识符包含在您的 App ID 中，并且您的 App ID 已在您的 Apple Developer 账户中注册。

如果您有仅在应用程序的特定 flavor 中使用的资源，您可以配置它们，以便仅在启动该 flavor 时将它们捆绑到您的应用程序中。这可以防止您的应用程序捆绑包大小因未使用的资源而膨胀。要为每个 flavor 捆绑资源，请将 flavors 子字段添加到项目 pubspec 文件中的 assets 字段中。要了解更多信息，请参阅 assets 字段 在 Flutter pubspec 选项 中。

如果您正在为 Flutter iOS 项目创建新的 Xcode schemes，并且在现有的 Flutter 项目中有一个 iOS Podfile，则必须更新 Flutter iOS Podfile 以匹配您在 Xcode 中所做的更改。

以下步骤展示了如何更新您的 iOS Podfile，以包含名为 staging 和 production 的两个新的 Xcode schemes，在名为 flavors_example 的 Flutter 项目中。您也可以通过将任何对 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 flavors 的一种方法是将这些构建设置分配给 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。

有关创建和使用 flavors 的更多信息，请查看以下资源

• 如何使用 FlutterFire CLI 设置具有多个 flavors 的 Flutter 和 Firebase
• Flutter Ready to Go 中的 Flutter (Android 和 iOS) flavors，每个 flavor 具有不同的 Firebase 项目