为 Android 配置 flavor

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

Flutter flavor 用于 Android 时，是各种平台特定特性的统一称呼。例如，一个 flavor 可以决定应用某个特定版本所关联的图标、应用名称、 API key、功能开关 (feature flag) 以及日志级别。

如果你想为 Android 应用创建 Flutter flavor，可以在 Flutter 中完成。在 Android 中，Flutter flavor 被称为 产品 flavor (product 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 构建类型。

   console

   $ 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：

     console

     $ 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>): Replace this with one of the following:

  • run: Runs the app in debug mode.
  • build: Builds either an APK or an appbundle.
    • <subcommand>: Either apk or appbundle.

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

  • run：以 debug 模式运行应用。
  • build：构建 APK 或 appbundle。
    • <subcommand>：apk 或 appbundle。

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

例如：

$ flutter build apk --flavor staging

配置好产品 flavor 后，你可以根据当前生效的 flavor 来改变应用的行为—— 例如指向不同的 API 端点或更换主题。

Flutter 框架提供了 appFlavor 常量，它以 String 形式获取当前 flavor 的名称。该值与 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 的项目中，为 staging 和 production 两个产品 flavor 添加独特的应用显示名称。

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，请参阅 启动某个 flavor 中的步骤。

   • 在 Android 应用模拟器中，进入应用列表。你应该会看到一个 Flavors p... 和一个 Flavors s...。

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

如果你有多个产品 flavor，为每种配置准备一个独特的图标，能帮你快速识别已部署的应用使用的是哪个 flavor。

以下步骤演示如何在名为 flavors_example 的项目中，为 staging 和 production 两个产品 flavor 添加独特的图标。

1. 准备你的图标：

   • 用你喜欢的设计工具设计 staging 图标和 production 图标。

   • 以 PNG 格式生成以下尺寸的 staging 图标和 production 图标：

     • 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 中的步骤。

如果你的应用中有些资源 (assets) 只在特定 flavor 中使用，你可以配置它们仅在启动该 flavor 时才被打包进应用。这能避免未使用的资源使应用包体积膨胀。要为每个 flavor 打包资源，请在项目 pubspec 的 assets 字段中添加 flavors 子字段。要了解更多，请参阅 Flutter pubspec 选项 中的 assets 字段。

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

如果你想为某个特定的 Android 产品 flavor 配置额外的构建设置，请参阅 Android 的 配置构建变体。

虽然可以在产品 flavor 中设置 abiFilters，但并不推荐这样做。更建议在 defaultConfig 中设置 abiFilters。如果在产品 flavor 中设置了 abiFilters，请在运行 flutter build 或 flutter run 时必须使用 -Pdisable-abi-filtering=true 参数。

要了解更多关于创建和使用 flavor 的信息，请查看以下资源：

• 在 Flutter（Android 与 iOS）中使用 Firebase 构建 flavor (Build flavors in Flutter (Android and iOS) with Firebase)

• 如何使用 FlutterFire CLI 为 Flutter 与 Firebase 配置多个 flavor (How to Setup Flutter & Firebase with Multiple Flavors using the FlutterFire CLI)