为 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