干货：在Flutter项目下安卓flavor打包配置实践

productFlavors {
    // 生产环境
    flavoronline {
        applicationId "com.sohu.flavor"
    }
    // 开发环境
    flavordev {
        applicationId "com.sohu.flavor.dev"
    }
    // 测试环境
    flavortest {
        applicationId "com.sohu.flavor.test"
    }
}

需要注意的是，所有的Flavor名称都需要是小写的，原因之后的章节会进行说明。

2.2为不同Flavor配置入口文件 

Flutter项目并没有类似BuildConfig这样自动生成不同Flavor下的配置文件。如果读取Android层的BuildConfig文件需要通过MethodChannel，异步获取。在现实场景中，冷启动的时候就需要根据Flavor上报一些数据，或进行业务处理。所以在不同的Flavor下，Flutter建议在App初始化时指定不同的入口文件来进行不同配置的实现，实现方式如下：我们知道默认情况下，Flutter工程的入口文件是为lib/main.dart。为了实现多入口，我们需要写三个Flavor的入口文件来替代main.dart。分别为：

1.main_android_dev.dart

import 'package:flutter/material.dart';
import 'package:supermarie/common/config/app_config.dart';
import 'package:supermarie/my_app.dart';
 
void main() {
  AppConfig.init(ConfigType.androidDev);
  runApp(MyAppDev());
}
 
class MyAppDev extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MyApp();
  }
}

2.main_android_test.dart

import 'package:flutter/material.dart';
import 'package:supermarie/common/config/app_config.dart';
import 'package:supermarie/my_app.dart';
 
void main() {
  AppConfig.init(ConfigType.androidTest);
  runApp(MyAppTest());
}
 
class MyAppTest extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MyApp();
  }
}

3.main_android_online.dart

import 'package:flutter/material.dart';
import 'package:supermarie/common/config/app_config.dart';
import 'package:supermarie/my_app.dart';
 
void main() {
  AppConfig.init(ConfigType.androidOnline);
  runApp(MyAppOnline());
}
 
class MyAppOnline extends StatelessWidget {
 
  @override
  Widget build(BuildContext context) {
    return MyApp();
  }
}

其中AppConfig.init()方法为根据不同Flavor进行的初始化操作。如：配置Host，各种id，key等。接着再执行'runApp()'方法。而MyApp()是走完配置后统一的程序入口，即App的首页展示。其结构如图所示：

2.3 不同Flavor及不同入口的打包 

Flavor和入口文件配置完成后，我们可以尝试打包了，打包方式如下：flutter build apk --[debug/release] --flavor [flavor] -t [entrance]参数说明：[debug/release]：指定debug或release，[flavor]：指定Flavor，[entrance]：指定入口文件名称。所以三个Flavor，总共六个包的打包令分别为：

//开发环境：
flutter build apk --debug --flavor flavordev -t lib/main_android_dev.dart
flutter build apk --release --flavor flavordev -t lib/main_android_dev.dart
//测试环境：
flutter build apk --debug --flavor flavortest -t lib/main_android_test.dart
flutter build apk --release --flavor flavortest -t lib/main_android_test.dart
//生产环境：
flutter build apk --debug --flavor flavoronline -t lib/main_android_online.dart
flutter build apk --release --flavor flavoronline -t lib/main_android_online.dart

如果一切正常的情况下，我们就会在项目根目录/build/app/outputs/app/[flavor]/[debug/release]下看到生成的apk文件了。好，Flutter项目下Android工程的Flavor设置及打包已经完成了。下一章将通过源码解析来梳理Flutter项目Android包的打包流程。

3.Flutter Android构建过程详解 

Flutter项目的构建入口文件位于：fluttersdk/packages/flutter_tools/bin下的flutter_tools.dart文件，这是所有平台的构建入口，代码如下：

import 'package:flutter_tools/executable.dart' as executable;

void main(List<String> args) {
  executable.main(args);
}

main()函数里只有一行代码，执行了executable.dart的main()方法，我们继续看它的实现：

//skip 
//...

  await runner.run(args, () => <FlutterCommand>[
//skip 
//...
    BuildCommand(verboseHelp: verboseHelp),
//skip 
//...
  ], verbose: verbose,
     muteCommandLogging: muteCommandLogging,
     verboseHelp: verboseHelp,
     overrides: <Type, Generator>{
//skip 
//...
     });
}

这段代码比较长，会初始化很多command指令，然后再依次执行。但由于我们分析的是apk的构建流程，所以我们只看BuildCommand()的执行过程。

  BuildCommand({ bool verboseHelp = false }) {
    addSubcommand(BuildAarCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildApkCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildAppBundleCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildAotCommand());
    addSubcommand(BuildIOSCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildIOSFrameworkCommand(
      buildSystem: globals.buildSystem,
      verboseHelp: verboseHelp,
    ));
    addSubcommand(BuildBundleCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildWebCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildMacosCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildLinuxCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildWindowsCommand(verboseHelp: verboseHelp));
    addSubcommand(BuildFuchsiaCommand(verboseHelp: verboseHelp));
  }

BuildCommand()中添加了很多子command指令，用于不同平台或生成文件的构建。由于我们分析的是apk的打包，接下来继续看BuildApkCommand()的实现，位于fluttersdk/packages/flutter_tools/lib/src/commands/build_apk.dart：

class BuildApkCommand extends BuildSubCommand {
  BuildApkCommand({bool verboseHelp = false}) {
    addTreeShakeIconsFlag();
    usesTargetOption();
//skip
//...
  }
//skip
//...

  @override
  Future<FlutterCommandResult> runCommand() async {
//skip
//...
    await androidBuilder.buildApk(
      project: FlutterProject.current(),
      target: targetFile,
      androidBuildInfo: androidBuildInfo,
    );
    return FlutterCommandResult.success();
  }
}

我们看到BuildApkCommand()的构造方法先进行了一些初始化配置。回到之前executable.main()方法，如果我们继续跟踪runner.run()方法，执行command的实现，实际上就是执行各个command以及其子command的代码，在执行到BuildApkCommand()时，调用了其runCommand()方法，如上述代码所示。这个方法的核心实现就是androidBuilder.buildApk()，我们接着看androidBuilder.buildApk()的实现：

  @override
  Future<void> buildApk({
    @required FlutterProject project,
    @required AndroidBuildInfo androidBuildInfo,
    @required String target,
  }) async {
    try {
      await buildGradleApp(
        project: project,
        androidBuildInfo: androidBuildInfo,
        target: target,
        isBuildingBundle: false,
        localGradleErrors: gradleErrors,
      );
    } finally {
      globals.androidSdk?.reinitialize();
    }
  }

其中核心代码buildGradleApp()方法的位置在fluttersdk/packages/flutter_tools/lib/src/android/gradle.dart下。从文件的命名中即可得知，这个文件跟Android的gradle文件是密切相关的。我们截取buildGradleApp()方法核心部分的实现：

Future<void> buildGradleApp({
  @required FlutterProject project,
  @required AndroidBuildInfo androidBuildInfo,
  @required String target,
  @required bool isBuildingBundle,
  @required List<GradleHandledError> localGradleErrors,
  bool shouldBuildPluginAsAar = false,
  int retries = 1,
}) async {
//skip
//...
  // The default Gradle script reads the version name and number
  // from the local.properties file.
  updateLocalProperties(project: project, buildInfo: androidBuildInfo.buildInfo);
//skip
//...

  final BuildInfo buildInfo = androidBuildInfo.buildInfo;
  final String assembleTask = isBuildingBundle
    ? getBundleTaskFor(buildInfo)
    : getAssembleTaskFor(buildInfo);

  final Status status = globals.logger.startProgress(
    "Running Gradle task '$assembleTask'...",
    timeout: timeoutConfiguration.slowOperation,
    multilineOutput: true,
  );

  final List<String> command = <String>[
    gradleUtils.getExecutable(project),
  ];
//skip
//...
  command.add(assembleTask);
//skip
//...
  final Stopwatch sw = Stopwatch()..start();
  int exitCode = 1;
  try {
    exitCode = await processUtils.stream(
      command,
      workingDirectory: project.android.hostAppGradleRoot.path,
      allowReentrantFlutter: true,
      environment: gradleEnvironment,
      mapFunction: consumeLog,
    );
  } on ProcessException catch (exception) {
    consumeLog(exception.toString());
    // Rethrow the exception if the error isn't handled by any of the
    // `localGradleErrors`.
    if (detectedGradleError == null) {
      rethrow;
    }
  } finally {
    status.stop();
  }
//skip
//...

  // Gradle produced an APK.
  final Iterable<String> apkFilesPaths = project.isModule
    ? findApkFilesModule(project, androidBuildInfo)
    : listApkPaths(androidBuildInfo);
  final Directory apkDirectory = getApkDirectory(project);
  final File apkFile = apkDirectory.childFile(apkFilesPaths.first);
  if (!apkFile.existsSync()) {
    _exitWithExpectedFileNotFound(
      project: project,
      fileExtension: '.apk',
    );
  }

//skip
//...

从代码中我们可得知，在buildGradleApp()方法中会读取并修改local.properties的属性，local.properties是根据Flutter的pubspec.yaml文件等配置生成的本地文件。然后根据buildInfo获取assembleTask，设置当前的编译状态status，初始化command数组，并将assembleTask加入其中。接着执行command列表，其中一个command即调用gradle执行assembleTask。执行完成后，生成apk文件，进行构建检查，然后构建结束。既然执行到gradle文件了，我们再来看看Flutter项目下的gradle文件和普通Android工程的gradle文件有什么不同：

def localProperties = new Properties()
def localPropertiesFile = rootProject.file('local.properties')
if (localPropertiesFile.exists()) {
    localPropertiesFile.withReader('UTF-8') { reader ->
        localProperties.load(reader)
    }
}

def flutterRoot = localProperties.getProperty('flutter.sdk')
if (flutterRoot == null) {
    throw new GradleException("Flutter SDK not found. Define location with flutter.sdk in the local.properties file.")
}

def flutterVersionCode = localProperties.getProperty('flutter.versionCode')
if (flutterVersionCode == null) {
    flutterVersionCode = '1'
}

def flutterVersionName = localProperties.getProperty('flutter.versionName')
if (flutterVersionName == null) {
    flutterVersionName = '1.0'
}

apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"
//skip
//...

这是截取项目中的gradle文件，不同之处都在头部。首先是读取localProperties的属性，主要判断flutter sdk是否存在，以及获取app的versionCode和versionName。然后在执行项目其他gradle配置之前，先执行sdk中的flutter.gradle文件。位置在：fluttersdk/packages/flutter_tools/gradle/flutter.gradle。其结构如下：

flutter.gradle这个文件代码很长，但从这张图上，我们可以很清晰的看出结构。主要任务就是执行了FlutterPlugin，在FlutterPlugin中定义了FlutterTask这个任务，而FlutterTask必然承载了Flutter的编译过程。FlutterTask的核心代码如下：

    @TaskAction
    void build() {
        buildBundle()
    }

buildBundle()方法就是根据不同的配置，执行了各种flutter的编译指令，比如之前示例代码中，我们通过-t指定flutter层的程序入口。由于这部分已经出离本文的讨论范围，先不做展开了。大家只要知道这部分执行完成后最终生成了Flutter层的编译产物即可。经过了原生层和Flutter层的构建，整个Flutter项目的Android apk构建流程就梳理完毕了。构建思路已经非常清晰，但是在打包过程中，我们发现了新的问题，使我们对构建流程的一些细节进行了梳理，下一章将对打包过程中的bug和原因进行说明。

4.Flutter SDK打包bug说明 

我们回到Flavor设置及打包这个章节的开始的Flavor配置示例：

productFlavors {
    // 生产环境
    flavoronline {
        applicationId "com.sohu.flavor"
    }
    // 开发环境
    flavordev {
        applicationId "com.sohu.flavor.dev"
    }
    // 测试环境
    flavortest {
        applicationId "com.sohu.flavor.test"
    }
}

在最一开始的配置示例中，我们说明了在gradle文件中配置的Flavor名称必须是小写的。但实际上一开始我们是用的驼峰命名，即：flavorOnline, flavorDev, flavorTest。这是因为我们开发过程是在macOS系统下进行的，打包是在Ubuntu系统下通过jenkins打包完成的。在开发过程中，我们打各个环境下的包都完全没有问题，但是在Ubuntu系统下，会报如下错误：

Gradle build failed to produce an .apk file. It's likely that this file was generated under XXX(目录), but the tool couldn't find it.

通常情况下，这个问题的出现是因为在多渠道打包时，打包命令没有指定相应的入口文件或渠道名称，但实际上我们的打包命令是没有问题的，而且我们在XXX目录下找到了apk文件，这些apk文件在安装运行过程中也都没有任何问题。那么这个问题是怎么出现的呢？先说结论，经过验证，这个是flutter sdk(1.22.4)的一个bug。再说明原因之前，说明一下针对此问题的三种可行解决方案。

1.不作任何处理，每次安装apk包都通过adb install命令去安装。jenkins上虽然每次都会提示打包失败，但实际上打包文件都在，也都会显示在页面中。

2.Flavor名称全小写，也就是我们最终的实现方案。

3.修改flutter sdk中的gradle.dart文件第488行为：

final File apkFile = apkDirectory.childFile(apkFilesPaths.first.toLowerCase());

接下来我们分析一下问题产生的原因：比如我们打一个debug flavorDev的包，打包完成后在XXX目录下为：app-flavordev-debug.apk。我们回到gradle.dart文件，看看打包完成后的执行内容，主要是做一些检查工作：

  // Gradle produced an APK.
  final Iterable<String> apkFilesPaths = project.isModule
    ? findApkFilesModule(project, androidBuildInfo)
    : listApkPaths(androidBuildInfo);
  final Directory apkDirectory = getApkDirectory(project);
  final File apkFile = apkDirectory.childFile(apkFilesPaths.first);
  if (!apkFile.existsSync()) {
    _exitWithExpectedFileNotFound(
      project: project,
      fileExtension: '.apk',
    );
  }

void _exitWithExpectedFileNotFound({
  @required FlutterProject project,
  @required String fileExtension,
}) {
  assert(project != null);
  assert(fileExtension != null);
 
  final String androidGradlePluginVersion =
  getGradleVersionForAndroidPlugin(project.android.hostAppGradleRoot);
  BuildEvent('gradle-expected-file-not-found',
    settings:
    'androidGradlePluginVersion: $androidGradlePluginVersion, '
      'fileExtension: $fileExtension',
    flutterUsage: globals.flutterUsage,
  ).send();
  throwToolExit(
    'Gradle build failed to produce an $fileExtension file. '
    "It's likely that this file was generated under ${project.android.buildDirectory.path}, "
    "but the tool couldn't find it."
  );
}

其中apkFilesPaths是需要检查的apk路径，通过apkFilesPaths拿到apkFile文件名称，接着对apkFile文件进行检查，如果不存在则报如上所述异常。我们看看apkFilesPaths是如何生成的，由于project.isModule为false，所以直接看listApkPaths()的实现：

Iterable<String> listApkPaths(
  AndroidBuildInfo androidBuildInfo,
) {
  final String buildType = camelCase(androidBuildInfo.buildInfo.modeName);
  final List<String> apkPartialName = <String>[
    if (androidBuildInfo.buildInfo.flavor?.isNotEmpty ?? false)
      androidBuildInfo.buildInfo.flavor,
    '$buildType.apk',
  ];
  if (androidBuildInfo.splitPerAbi) {
    return <String>[
      for (AndroidArch androidArch in androidBuildInfo.targetArchs)
        <String>[
          'app',
          getNameForAndroidArch(androidArch),
          ...apkPartialName
        ].join('-')
    ];
  }
  return <String>[
    <String>[
      'app',
      ...apkPartialName,
    ].join('-')
  ];
}

这段代码说明检查的apk的命名方式为：'app-' + androidBuildInfo.buildInfo.flavor + '$buildType.apk'。所以apkFilesPaths.first的结果如下：

app-flavorDev-debug.apk

回过头来看XXX目录下的apk文件：app-flavordev-debug.apk，发现差了一个大小写。所以猜测是大小写问题导致的。我们修改gradle.dart的以下代码：

final File apkFile = apkDirectory.childFile(apkFilesPaths.first);

为：

final File apkFile = apkDirectory.childFile(apkFilesPaths.first.toLowerCase());

即检查的apkFile的文件名称强制转成小写，发现build成功不会再报错。那为什么在macOS就不会报错呢？大概是因为不同os在针对检查文件一致性的方式不同。Ubuntu系统下会针对文件名称大小写进行严格检查。

注意：为了让Flutter sdk修改的内容生效，修改代码后需删除fluttersdk/flutter/bin/cache路径下的flutter_tools.snapshot和flutter_tools.stamp重新编译sdk。

另外，我们知道在gradle文件下可以指定输出的文件名称，这个是没有问题的。但是flutter sdk中的flutter.gradle(fluttersdk/packages/flutter_tools/gradle/flutter.gradle)依旧会在XXX目录下输出相应的小写文件，此处可看flutter.gradle的相应实现：

variant.outputs.all { output ->
    // `assemble` became `assembleProvider` in AGP 3.3.0.
    def assembleTask = variant.hasProperty("assembleProvider")
        ? variant.assembleProvider.get()
        : variant.assemble
    assembleTask.doLast {
//skip
//...
        if (variant.flavorName != null && !variant.flavorName.isEmpty()) {
            filename += "-${variant.flavorName.toLowerCase()}"
        }
        filename += "-${buildModeFor(variant.buildType)}"
        project.copy {
            from new File("$outputDirectoryStr/${output.outputFileName}")
            into new File("${project.buildDir}/outputs/flutter-apk");
            rename {
                return "${filename}.apk"
            }
        }
    }
}

所以为了保证打包成功，在不修改sdk源码的情况下，我们需将Flavor设置成小写即可绕过这个bug。最后说明一下，目前在Flutter sdk的master分支上，此bug已修复。在gradle.dart文件中，会检查小写文件，listApkPaths()的实现如下：

Iterable<String> listApkPaths(
  AndroidBuildInfo androidBuildInfo,
) {
  final String buildType = camelCase(androidBuildInfo.buildInfo.modeName);
  final List<String> apkPartialName = <String>[
    if (androidBuildInfo.buildInfo.flavor?.isNotEmpty ?? false)
      androidBuildInfo.buildInfo.lowerCasedFlavor,
    '$buildType.apk',
  ];
//skip
//...
}

可以看到apkPartialName返回的第1位是：androidBuildInfo.buildInfo.lowerCasedFlavor，在取Flavor的时候，直接取小写属性。所以大家也可以耐心等待，新的稳定版发布后，这个bug应该就fix了。

5.总结 

经过实践，最终我们的Flutter项目Android端，使用以上方式进行了Flavor配置与属性读取。并且本文通过源码解析梳理了整个构建流程，希望能够帮助大家更好的理解Flutter是如何进行apk构建的。另外在实践过程中，发现了sdk在打包过程中的一个bug，且给出了解决方案可以在不修改源码的情况下绕过此问题。

6.参考文献