为 iOS 和 macOS 设置 Flutter 风味

本指南介绍了如何为 iOS 或 macOS 应用创建 Flutter 风味。

Flutter 风味本质上是一组设置的集合，它定义了应用的特定版本应如何构建和运行。例如，一个风味可以决定与应用特定版本关联的图标、应用名称、API 密钥、功能标志和日志级别。

如果您想为 iOS 应用创建 Flutter 风味，则需要在 Xcode 中进行操作。Xcode 没有名为“风味”的概念。相反，您需要设置一个名为 Scheme 的东西，并为其附加自定义配置。

下图展示了两个 Flutter 风味（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 工作区。

   控制台

   cd flavors_example && open ios/Runner.xcworkspace

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

   • 打开项目导航器（视图 > 导航器 > 项目）。

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

4. 在 Xcode 中创建 Scheme

   • 打开新建 Scheme 窗口（产品 > Scheme > 新建 Scheme）。

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

   • 在名称框中，输入 staging。

   • 点击确定添加新 Scheme。

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

   • 完成后，检查确保您有以下 Scheme：

     

5. 在 Xcode 中为 Scheme 创建配置

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

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

   • 如果信息选项卡未打开，请将其打开。

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

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

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

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

     

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

   • 打开管理 Scheme 窗口（产品 > Scheme > 管理 Scheme）。

   • 选择 staging Scheme 并编辑它。

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

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

   • 点击关闭。

   • 对 production Scheme 重复上述步骤。

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

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

   • 选择 staging Scheme（产品 > Scheme > staging）。

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

     

   • 运行应用 Scheme（产品 > 运行）。

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

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

   示例

   控制台

   flutter run --flavor staging

您可以使用以下步骤在 Xcode 中启动特定 Scheme：

1. 选择您要测试的 Scheme（产品 > Scheme > 选择 Scheme）。

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

3. 运行应用 Scheme（产品 > 运行）。

添加 Xcode Scheme 后，您可以为 iOS 应用自定义它们。您也可以通过将所有 iOS 替换为 macOS 来使用这些步骤配置 macOS 项目。

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

以下步骤展示了如何在 Xcode 中为名为 flavors_example 的项目中的两个 Scheme（staging 和 production）添加不同的应用显示名称。

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

   • 打开项目导航器（视图 > 导航器 > 项目）。

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

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

   • 打开构建设置选项卡。

   • 在“基本”选项卡左侧，点击+并选择添加用户定义设置。

   • 创建名为 APP_DISPLAY_NAME 的设置。

   • 展开APP_DISPLAY_NAME 设置。

   • 将以下值分配给以下键：

     • Debug-production: 风味 prod
     • Debug-staging: 风味 staging
     • Profile-production: 风味 prod
     • Profile-staging: 风味 staging
     • Release-production: 风味 prod
     • Release-staging: 风味 staging

2. 在 Xcode 中更新 Info.plist

   • 在项目导航器中，选择Runner > Runner > 信息以打开 flavor_test/ios/Runner/Info.plist。

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

     • 键: CFBundleDisplayName
     • 值: $(APP_DISPLAY_NAME)

3. 为每个 Scheme（staging、production）启动应用，并检查确保每个应用的显示名称都已更改。要启动 Scheme，请参阅启动 Xcode Scheme 中的步骤。

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

以下步骤展示了如何在 Xcode 中为名为 flavors_example 的 iOS 项目中的两个 Scheme（staging 和 production）添加不同的图标。

1. 准备您的图标

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

   • 生成所需大小的 staging 图标和 production 图标版本。将它们保存为 PNG 格式。

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

   • 打开项目导航器（视图 > 导航器 > 项目）。

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

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

     • 点击+ > iOS > iOS 应用图标。

     • 将图标命名为 AppIcon-staging。

     • 将您的 staging 图标拖到AppIcon-staging窗口中，并确保图标分配到正确的大小。

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

3. 将图标连接到您的 Scheme

   • 打开项目导航器。

   • 在目标下的主窗口中，选择 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 中的步骤。

Bundle 标识符是您的应用在 Apple 平台上的唯一标识符。如果您将多个 Xcode Scheme 用作 Flutter 风味，您可以让 Apple 将每个 Scheme 视为一个单独的应用。为此，您需要为每个 Scheme 分配一个不同的 Bundle 标识符。这使您可以在不影响应用另一个版本（例如 production）的情况下，在一个应用版本（例如 staging）中测试新功能或错误修复。

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

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

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

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

4. 导航到打包部分。

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

6. 对于每个 Scheme 的构建配置，设置所需的 Bundle 标识符。例如：

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

     com.example.flavorsExample.staging

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

     com.example.flavorsExample

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

如果您的应用中有某些资源仅在特定风味中使用，您可以配置它们，使其仅在该风味启动时才打包到您的应用中。这可以防止您的应用包大小因未使用的资源而膨胀。要为每个风味打包资源，请将 flavors 子字段添加到您项目 pubspec 中的 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,
     ...

您可以使用构建设置来管理您的 iOS 构建过程，从编译和链接到调试和分发。将构建设置与 Flutter 风味结合使用的一种方法是将这些构建设置分配给 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。

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

• 如何使用 FlutterFire CLI 设置具有多个风味的 Flutter & Firebase
• 在 Flutter 中构建风味（Android 和 iOS），每个风味对应不同的 Firebase 项目 Flutter Ready to Go