设置 Android 版 Flutter Flavors

本指南向你展示如何为 Android 应用创建 Flutter Flavor。

当与 Android 一起使用时，Flutter Flavor 是各种平台特定功能的一个统一术语。例如，Flavor 可以决定与应用特定版本关联的图标、应用名称、API 密钥、功能标志 (feature flag) 和日志级别。

如果你想为 Android 应用创建 Flutter Flavor，可以在 Flutter 中完成。在 Android 中，Flutter Flavor 被称为 product flavor (产品 Flavor)。

下图展示了当 Android 应用具有两个产品 Flavor（staging、production）和两个构建类型（debug、release）时所创建的 Android 构建变体 (build variants) 的示例：

完成以下步骤，为一个名为 flavors_example 的新 Flutter 项目添加两个名为 staging 和 production 的 Android 产品 Flavor，然后测试你的项目以确保 Flavor 按预期工作。

1. 创建一个名为 flavors_example 的新 Flutter 项目，并将 Kotlin 作为首选 Android 语言。默认情况下，该项目包含 debug 和 release Android 构建类型。

   控制台

   $ flutter create --android-language kotlin flavors_example
   

   content_copy

2. 将名为 staging 和 production 的产品 Flavor 添加到 flavors_example 项目中。

   • 在 flavors_example 项目中，导航到 android/app/ 目录并打开 build.gradle.kts。

   • 在 android {} 代码块内添加 flavorsDimension 属性和 productFlavors 属性。确保 android {} 代码块中也包含默认的 debug 和 release 构建类型。

     build.gradle.kts

     kotlin

     android {
         ...
         buildTypes {
           getByName("debug") {...}
           getByName("release") {...}
         }
         ...
         flavorDimensions += "default"
         productFlavors {
             create("staging") {
                 dimension = "default"
                 applicationIdSuffix = ".staging"
             }
             create("production") {
                 dimension = "default"
                 applicationIdSuffix = ".production"
             }
         }
     }
     

     content_copy

3. 为了确保你已正确设置所有内容，请在 Android 产品 Flavor 上运行你的应用。由于配置设置尚未更改，你不会看到任何差异，但你需要确保应用能够运行。

   • 启动 Android 模拟器或连接启用了开发者选项的物理设备。

   • 在控制台中，导航到 flavors_example 目录并输入以下命令来测试 staging Flavor：

     控制台

     $ flutter run --flavor staging
     

     content_copy

   • 对 production Flavor 重复上一步。

4. 如果一切运行正常，你就可以自定义配置了。有关更多信息，请参阅 自定义配置。

为 Android 应用创建产品 Flavor 后，你可以通过 Flutter 启动特定的产品 Flavor。

你可以按照以下步骤使用 Flutter CLI 启动产品 Flavor：

1. 启动 Android 模拟器或连接启用了开发者选项的物理设备。

2. 在控制台中，导航到 flavors_example 目录并输入以下命令：

$ flutter (run | build <subcommand>) --flavor <flavor_name>

• (run | build <subcommand>)：将其替换为以下其中之一：

  • run：在调试模式下运行应用。
  • build：构建 APK 或 App Bundle。
    • <subcommand>：apk 或 appbundle。

• <flavor_name>：将其替换为你的 Android 产品 Flavor 名称（例如：staging、production）。

示例

$ flutter build apk --flavor staging

配置完产品 Flavor 后，你可以根据活动的 Flavor 更改应用的行为，例如指向不同的 API 端点或更改主题。

Flutter 框架提供了 appFlavor 常量，它将当前 Flavor 的名称作为 String 检索。此值与 flutter run 或 flutter build 过程中传递给 --flavor 标志的 Flavor 名称匹配。

1. 导入 services 库：要访问 appFlavor 常量，请将以下导入添加到你的 Dart 文件中：

   dart

   import 'package:flutter/services.dart';
   

   content_copy

2. 检查 Flavor 值：在你的应用逻辑（通常在 main() 中）中使用 appFlavor 常量来处理特定于 Flavor 的配置：

   dart

   void main() {
     // appFlavor will match the flavor name from build.gradle.kts
     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

添加产品 Flavor 后，你可以为你的 Android 应用自定义它们。

如果你有多个产品 Flavor，不同的应用名称可以让你快速识别部署的应用正在使用哪个 Flavor。

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

1. 在 IDE 中更新 build.gradle.kts

   • 在 flavors_example 项目中，导航到 android/app/ 目录并打开 build.gradle.kts。

   • 在 flavorsDimension 代码块中，为 staging 和 production Flavor 添加一个名为 app_name 的 resValue() 属性：

     build.gradle.kts

     kotlin

     android {
         ...
         flavorDimensions += "default"
         productFlavors {
             create("staging") {
                 dimension = "default"
                 resValue(
                     type = "string",
                     name = "app_name",
                     value = "Flavors staging")
                 applicationIdSuffix = ".staging"
             }
             create("production") {
                 dimension = "default"
                 resValue(
                     type = "string",
                     name = "app_name",
                     value = "Flavors production")
                 applicationIdSuffix = ".production"
             }
         }
     

     content_copy

2. 在 IDE 中更新 AndroidManifest.xml

   • 在 flavors_example 项目中，导航到 android/app/src/main 并打开 AndroidManifest.xml。

   • 将 android:label 的值替换为 @string/app_name。

     AndroidManifest.xml

     xml

     <manifest xmlns:android="http://schemas.android.com/apk/res/android">
         <application
           android:label="@string/app_name"
           ...
         />
     />
     

     content_copy

3. 为每个产品 Flavor（staging、production）启动应用，并检查确保每个应用显示名称都已更改。

   • 要启动产品 Flavor，请参阅 启动 Flavor 中的步骤。

   • 在 Android 应用模拟器中，转到应用列表。你应该能看到 Flavors p... 和 Flavors s... 的应用。

   • 要查看 Flavors p... 或 Flavors s... 的更多信息，请长按其中一个图标并选择 App info (应用信息)。

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

以下步骤展示了如何为一个名为 flavors_example 的项目中的两个产品 Flavor（staging 和 production）添加不同的图标。

1. 准备你的图标

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

   • 按以下尺寸生成 staging 图标和 production 图标的 PNG 版本：

     • mipmap-mdpi (48x48 像素)
     • mipmap-hdpi (72x72 像素)
     • mipmap-xhdpi (96x96 像素)
     • mipmap-xxhdpi (144x144 像素)
     • mipmap-xxxhdpi (192x192 像素)

2. 创建特定于 Flavor 的资源目录

   • 导航到 android/app/src 目录。

   • 创建一个名为 staging/res 的目录。

   • 导航到 staging/res 目录。

   • 创建以下 mipmap 目录并将 staging 图标的版本移动到其中：

     • mipmap-mdpi/48x48_staging.png
     • mipmap-hdpi/72x72_staging.png
     • mipmap-xhdpi/96x96_staging.png
     • mipmap-xxhdpi/144x144_staging.png
     • mipmap-xxxhdpi/192x192_staging.png

   • 对 production Flavor 的目录和图标重复上述步骤。

   • 将所有图标重命名为 ic_launcher.png。

3. 在 IDE 中仔细检查 AndroidManifest.xml 中的配置

   • 在 flavors_example 项目中，导航到 android/app/src/main 并打开 AndroidManifest.xml。

   • 确保 android:icon 的值为 @mipmap/ic_launcher。

4. 为每个产品 Flavor（staging、production）启动应用，并检查确保每个应用图标都已更改。要启动产品 Flavor，请参阅 启动 Flavor 中的步骤。

如果你的应用中有仅在特定 Flavor 中使用的资源，你可以将它们配置为仅在启动该 Flavor 时打包进应用。这可以防止你的应用包体积因未使用的资源而增大。要为每个 Flavor 打包资源，请将 flavors 子字段添加到项目 pubspec 中的 assets 字段。要了解更多信息，请参阅 Flutter pubspec 选项 中的 assets 字段。

你可以在不指定 Flavor 的情况下启动应用时，让应用使用特定的 Flavor。为此，你需要将 default-flavor 字段添加到项目的 pubspec 中。要了解更多信息，请参阅 Flutter pubspec 选项 中的 default-flavor 字段。

如果你有其他想要为特定的 Android 产品 Flavor 配置的构建设置，请参阅 Android 的 配置构建变体 (Configure build variants)。

虽然可以在产品 Flavor 中设置 abiFilters，但不建议这样做。建议在构建类型 (build types) 中设置 abiFilters。在产品 Flavor 中设置 abiFilters 时，运行 flutter build 或 flutter run 时必须使用 -Pdisable-abi-filtering 标志。

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

• 使用 Firebase 在 Flutter (Android 和 iOS) 中构建 Flavor
• 如何使用 FlutterFire CLI 设置带有多个 Flavor 的 Flutter 和 Firebase