为 Android 设置 Flutter 应用变体

本指南介绍了如何为 Android 应用创建 Flutter 应用变体。

Flutter 应用变体与 Android 结合使用时，是各种平台特定功能的统一术语。例如，应用变体可以决定应用的特定版本关联的图标、应用名称、API 密钥、功能标志和日志级别。

如果您想为 Android 应用创建 Flutter 应用变体，可以在 Flutter 中完成。在 Android 中，Flutter 应用变体被称为 产品变体。

以下示例说明了当 Android 应用具有两个产品变体（staging、production）和两种构建类型（debug、release）时，所创建的 Android 构建变体：

完成以下步骤，将两个名为 staging 和 production 的 Android 产品变体添加到名为 flavors_example 的新 Flutter 项目中，然后测试您的项目以确保这些变体按预期工作。

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

   控制台

   flutter create --android-language kotlin flavors_example

2. 将名为 staging 和 production 的产品变体添加到 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"
             }
         }
     }

3. 为确保您已正确设置所有内容，请在 Android 产品变体上运行您的应用。您不会看到任何差异，因为配置设置尚未更改，但您确实需要确保应用可以运行。

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

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

     控制台

     flutter run --flavor staging

   • 为 production 应用变体重复上一步。

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

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

您可以使用 Flutter CLI 通过以下步骤启动产品变体：

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

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

   控制台

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

   • (run | build)：将其替换为以下任一选项：

     • run：在调试模式下运行应用。
     • build：在生产模式下运行应用。

   • <flavor_name>：将其替换为您的 Android 产品变体的名称（例如，staging 或 production）。

   示例

   控制台

   flutter run --flavor staging

添加产品变体后，您可以为 Android 应用自定义它们。

如果您有多个产品变体，独特的应用名称可以帮助您快速识别所部署应用正在使用的变体。

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

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

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

   • 在 flavorsDimension 块中，向 staging 和 production 变体添加名为 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"
             }
         }

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"
           ...
         />
     />

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

   • 要启动产品变体，请参阅启动应用变体中的步骤。

   • 在 Android 应用模拟器中，转到应用列表。您应该会看到 Flavors p... 和 Flavors s... 的应用图标。

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

如果您有多个产品变体，每个配置的独特图标可以帮助您快速识别所部署应用正在使用的变体。

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

1. 准备您的图标

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

   • 生成以下尺寸的 staging 图标和 production 图标版本，并将其保存为 PNG 格式：

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

2. 创建特定于应用变体的资源目录

   • 导航到 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 应用变体目录和图标重复上述步骤。

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

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

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

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

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

如果您的应用中存在仅在特定应用变体中使用的资产，您可以将其配置为仅在该应用变体启动时捆绑到您的应用中。这可以防止未使用的资产使您的应用包大小膨胀。要为每个应用变体捆绑资产，请将 flavors 子字段添加到您项目 pubspec 的 assets 字段中。要了解更多信息，请参阅 Flutter pubspec 选项中的 assets 字段。

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

如果您有其他希望为特定 Android 产品变体配置的构建设置，请参阅 Android 的配置构建变体。

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

• 使用 Firebase 在 Flutter（Android 和 iOS）中构建应用变体
• 如何使用 FlutterFire CLI 设置具有多个应用变体的 Flutter 和 Firebase