原生 Android 项目集成 Flutter Module 实战：从配置到上线

1. 为什么是 Flutter Module 而不是一个新的 Flutter 工程

1.1 很多团队一开始就走错了方向

我见过不少原生 Android 项目，想引入 Flutter，第一反应是 flutter create 创建一个完整的 Flutter App 工程，然后把 Android 原生代码塞进它的 android/ 目录里。这条路不是不能走，但它默认了一个前提：从这一刻起，Flutter 才是主角。目录、Gradle 工程、构建流程、依赖管理全部以 Flutter 为圆心，原生代码变成了“壳工程”里的客人。如果你正在主导一个已经跑了两三年的原生项目，团队主力还是 Android 工程师，这个前提大概率不成立。

Flutter Module 的思路正好反过来：原生工程还是原来的主人，Flutter 只是一个被请进来的“组件”。它不是一个独立 App，而是一个可以被 Android Gradle 工程直接依赖的 library。原生代码继续用之前的节奏迭代，某个二级页面、某个商品详情页、某个扫码结果页，想用 Flutter 重构，就单独把这一块做成 Flutter 页面，从原生 Activity 里跳进去。

1.2 判断标准：谁先启动，谁持有路由

选哪种方案，不要看技术热度，要看你的工程现状。我建议先用一个问题做判断：未来谁会先打开这个 App？

如果启动入口在 Android 原生，后续页面也大部分由原生控制，只是希望在某些页面用 Flutter 渲染，那不用犹豫，选 Module。如果你们的规划是整包演进，最终所有页面切到 Flutter，那也可以先用 Module 做过渡，把原生页面逐步迁成 Flutter 页面，而不是一上来就推倒重来。

还有一个隐含成本很多人没算：Flutter App 工程一旦建立，它的 android/ 目录会生成一套完整的 Gradle 构建配置，包括 applicationId、签名、渠道包逻辑。而原生工程往往有自己的多渠道、埋点、推送 SDK、第三方聚合，把两套体系强行合并，每次发版都会在 Gradle 配置上撕扯。用 Module 方式，Flutter 侧只需要关心 lib/ 下的业务代码，构建产物交给原生壳工程统一打包，配置冲突的范围会小很多。

1.3 Flutter Module 和 Flutter App 的边界对比

如果你的团队现状是“Android 为主、Flutter 逐步掌握”，Module 是最平滑的切入方式。当然，这也不是没有代价——混合工程在调试、依赖管理、引擎生命周期上会多出不少操作成本，后面几章我会逐个拆开讲。

2. 源码依赖与 AAR 分发：两种集成姿势如何选

2.1 源码依赖是日常开发的默认选项

源码依赖，就是把 Flutter Module 的源码目录直接关联到原生工程的 Gradle 构建里。在 settings.gradle 里把 flutter_module 加进来，然后在 app 模块的依赖里写上 implementation project(":flutter")。之后的构建会直接编译 Flutter Module 里的 Dart 代码，所有改动即时生效，热重载也能用。

这种方式的优点是链路短、直观，改完 Dart 代码，重新构建 APK 就是最新效果。缺点是它强依赖 Flutter SDK 在开发机上存在，而且 Gradle 配置和 Flutter 版本绑定得比较紧。如果你只是在一台电脑上的单体工程里开发，这个缺点基本可以忽略。

2.2 AAR 分发适合跨团队交付

另一种方式是先用 flutter build aar 把 Flutter Module 打成多个 AAR 包，再放到私有 Maven 仓库或本地目录，原生工程通过 implementation "com.example:flutter_module_release:1.0.0" 依赖。这个时候，原生团队完全不感知 Flutter SDK、Dart 代码、插件这些概念，拿到手的就是一堆普通的 Android 依赖。

这个模式适合什么样的团队？我遇到过两种典型情况：一种是 App 分多个业务线，支付组、商城组、内容组各自维护代码，Flutter Module 由独立的客户端中台团队统一打包；另一种是两家公司合作，A 公司提供 Flutter 能力，B 公司只负责接入，A 公司显然不能把自己的 Flutter 源码全部暴露给 B 公司。

2.3 我的选择建议

如果你还在前期验证，只用源码依赖。等接入稳定后，如果出现“两个 App 都要用同一套 Flutter 页面”的需求，再花半天时间把 flutter build aar 的 CI 流程搭起来。不要一开始就上 AAR，因为 AAR 方式的调试体验真的很憋屈，改一行 Dart 代码都要重新 build aar、上传、同步，原型期会被这个循环拖垮。

下面正文基于源码依赖展开，这也是我实际项目里最常用的路子。

3. 目录、版本与镜像准备：集成前最容易翻车的地方

3.1 推荐目录结构

先把工程目录理顺。常见做法是让原生 Android 工程和 Flutter Module 平级：

code复制projectRoot/
  androidApp/
    app/
    settings.gradle
    build.gradle
    gradle.properties
    gradlew
  flutter_module/
    lib/
    android/
    pubspec.yaml
    .metadata

原生工程命名为 androidApp，Flutter Module 目录用下划线命名 flutter_module。这个结构的好处是两者彼此独立，Flutter 侧可以单独用 Android Studio 打开，也可以和原生工程一起用同一个 IDE 窗口管理。

创建 Flutter Module 的命令是：

bash复制flutter create -t module --org com.example --project-name flutter_module flutter_module

--project-name 一定要和目录名一致，否则后面 Gradle 引用时会多出很多莫名其妙的路径问题。--org 会作为 Android 包名前缀，其实 Module 方式下 Flutter 的 applicationId 不会被真正当作 APK 包名，但保持规范总没错。

3.2 Flutter 与 Gradle/AGP 版本怎么配对

这是新手最容易踩的坑。Flutter Module 集成后的构建，本质是让 Flutter Gradle 插件跑在原生 Gradle 工程里，所以 Flutter SDK、AGP、Gradle 三个版本必须互相兼容。

我用的组合是 Flutter 3.16.x 系列配 AGP 8.1.x、Gradle 8.3 以上，Android Studio 用 Hedgehog（2023.1.1）以后的版本都没问题。如果你手里的 Flutter 版本更老，不要贸然升级 AGP 8，否则 plugin-loader 解析时会因为版本不匹配报错。

一个可靠的对照方法：到 Flutter SDK 目录的 packages/flutter_tools/gradle/src/main/kotlin/FlutterExtension.kt 里看它声明的 AGP 兼容范围，或者直接用官方默认模板生成的版本。官方模板永远是最稳的组合，如果项目里已经存在一套固定的 AGP 版本，优先降 Flutter 版本去适配它。

3.3 国内镜像与 SDK 源配置

Flutter 首次构建需要从网络拉取引擎产物和依赖，国内直连 google 经常抽风。比较好用的方式是配置镜像环境变量：

bash复制export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
export PUB_HOSTED_URL=https://pub.flutter-io.cn

这两个变量影响 Dart 包和 Flutter 引擎产物下载。如果你在用 Windows，在系统环境变量里加上，然后重启 Android Studio。配置完可以用 flutter doctor -v 验证，输出里会显示渠道和源。

实际开发中，我还会把 Gradle 的仓库源配成国内镜像，因为 Flutter 插件在解析时会向 maven.google.com 和 Maven Central 拉依赖：

groovy复制// settings.gradle
pluginManagement {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

需要注意的是，pluginManagement 放在 settings.gradle 顶部，顺序很重要。有些镜像仓库只能代理部分资源，所以 google() 和 mavenCentral() 也要保留，避免某些冷门插件拉不下来。

4. settings.gradle 改造：flutter-plugin-loader 和 include_flutter.groovy 分别解决什么问题

4.1 一段完整的 settings.gradle

先看一段实际可用的 settings.gradle，这是整个集成的核心：

groovy复制pluginManagement {
    def flutterSdkPath = {
        def properties = new Properties()
        file("local.properties").withInputStream { properties.load(it) }
        def flutterSdkPath = properties.getProperty("flutter.sdk")
        assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
        return flutterSdkPath
    }()

    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")

    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.1.4" apply false
    id "org.jetbrains.kotlin.android" version "1.9.22" apply false
}

include ":app"

setBinding(new Binding([gradle: this]))
evaluate(new File(
    settingsDir.parentFile,
    'flutter_module/.android/include_flutter.groovy'
))

include ":flutter_module"
project(":flutter_module").projectDir = new File("../flutter_module")

这段配置里有三件事各自独立，但缺一不可。

4.2 includeBuild 和 plugin-loader 在做什么

includeBuild("$flutterSdkPath/packages/flutter_tools/gradle") 是 Gradle 的复合构建语法，它把 Flutter SDK 自带的 Gradle 工具目录作为一个独立构建包含进来，这样后续就可以在插件块里使用 Flutter 提供的 Gradle 插件。

紧接着的 dev.flutter.flutter-plugin-loader 是 Flutter 3.x 之后的新机制。它会去查找 Flutter Module 中每个原生插件的注册信息（.flutter-plugins-dependencies 文件），再为这些插件生成 Gradle 的 include 配置。很多老项目没有这行，会用老式 apply 方式硬加载 Flutter 主插件，升级 Flutter 版本后就报出类似下面这种警告：

code复制You are applying Flutter's main Gradle plugin imperatively using the apply method

这个警告不是单纯吓唬人。新版本 Flutter 已经把主插件迁移到了 Plugin DSL 体系，继续用老式 apply 可能导致插件解析顺序错乱，最终报出 error resolving plugin [id: 'dev.flutter.flutter-plugin-loader']。

4.3 include_flutter.groovy 为什么还要再 evaluate 一次

Flutter Module 目录下的 .android 文件夹是 Flutter 自动生成的 Android 包装工程。它不是一个完整的、需要单独打开的工程，而是提供了一个 include_flutter.groovy 脚本，负责把 Flutter Module 内部的三方插件子模块挂载到当前原生工程里。

evaluate(new File(settingsDir.parentFile, 'flutter_module/.android/include_flutter.groovy')) 这一行会在 settings 阶段执行那个脚本，让 Flutter 插件对应的 Android 子模块出现在整个 Gradle 工程中。之后你再写 include ":flutter_module"，把 Flutter Module 本身也纳入依赖图。

到这里，原生工程和 Flutter Module 的 Gradle 视角已经打通了。如果你在集成后遇到“找不到 dev.flutter.flutter-plugin-loader”或者“Project with path :flutter could not be found”，九成是这一整段配置缺了其中一环，或者 local.properties 里的 flutter.sdk 没配置对。

5. app/build.gradle 依赖配置与老式 apply 用法的迁移

5.1 在 app 模块里声明 Flutter 依赖

settings.gradle 打通之后，app 模块的 build.gradle 只需要一行依赖：

groovy复制dependencies {
    implementation project(":flutter")
    // 其他现有依赖
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.11.0'
}

这里依赖的是 :flutter 而不是 :flutter_module，原因很简单：Flutter Module 本身不是 Android library，.android 目录下生成的 Flutter 组件才是一个可以被原生工程依赖的 library 模块，这个模块的名字就叫 flutter。

如果 app 模块是 Kotlin DSL（build.gradle.kts），写法也几乎一样：

kotlin复制dependencies {
    implementation(project(":flutter"))
}

5.2 根项目 build.gradle 里的老式 apply 迁移

老式集成方式里，根目录 build.gradle 往往长这样：

groovy复制buildscript {
    repositories { google() }
    dependencies {
        classpath 'com.android.tools.build:gradle:4.1.0'
    }
}

allprojects {
    repositories { google() }
}

// 老的写法：把 flutter 插件 apply 到整个工程
// apply from: "$flutterRoot/packages/flutter_tools/gradle/app_plugin_loader.gradle"

新工程直接删掉这段，把插件声明统一挪到 settings.gradle 的 plugins 块里，Plugin Management 会自动完成加载。如果项目里还残留 allprojects 那套，可以留着但不影响，新的 Flutter 插件解析不再依赖它。

我见过一个项目，升级后把 apply from: 那行注释掉了，但没把 buildscript 里的 classpath 依赖移除，结果 Gradle 解析时新旧两套插件加载机制互相干扰，报了很奇怪的类冲突。建议迁移时把根 build.gradle 里的 buildscript 依赖精简到只保留项目必要的类路径，Flutter 相关全部由 settings.gradle 的 pluginManagement 接管。

5.3 编译类型、Java 版本和依赖一致性

Flutter Module 编译后的 Android library 会有 debug、release、profile 三种变体，app 工程构建时会自动选择对应变体。所以你在 app 的构建类型里不需要特殊处理，只要确保 app 有 debug 和 release 两个 build type 即可。

Java/Kotlin 编译版本要留意。Flutter 的 Android 组件默认使用 Java 8 字节码，如果你的壳工程开了 compileOptions 升级到 Java 17，最好把 Flutter Module 的 android 目录下 build.gradle 里的 compileOptions 也同步到 Java 17，否则偶尔会出现 UnsupportedClassVersionError。最省事的方式是在根 build.gradle 里统一设置：

groovy复制subprojects {
    afterEvaluate { project ->
        if (project.plugins.hasPlugin("com.android.library")) {
            project.android {
                compileOptions {
                    sourceCompatibility JavaVersion.VERSION_17
                    targetCompatibility JavaVersion.VERSION_17
                }
            }
        }
    }
}

这段代码是“基于常见实践的补充”，不是 Flutter 官方默认行为，但它能解决 90% 混合编译版本不一致的问题。

6. 启动 Flutter 页面的三种姿势：直接 Intent、缓存引擎与 EngineGroup

6.1 直接用 Intent：最省事但别乱用

最常见的方式是从原生 Activity 跳到一个 FlutterActivity：

kotlin复制val intent = FlutterActivity.createDefaultIntent(this)
startActivity(intent)

createDefaultIntent 内部会创建一个全新的 FlutterEngine，加载主入口，然后显示页面。这个方式在 Demo 阶段足够，但实际业务里我会尽量避免，因为每次跳转都创建新引擎，内存开销和冷启动时间都会叠加。FlutterEngine 的初始化本身就有几十毫秒到上百毫秒的成本，不要小看这个延迟，用户在冷启动页面能明显感知。

6.2 FlutterEngineCache：预创建引擎再复用

更稳的做法是在原生侧提前创建一个 FlutterEngine，缓存起来，跳转时直接使用已缓存的引擎：

kotlin复制class App : Application() {
    lateinit var flutterEngine: FlutterEngine

    override fun onCreate() {
        super.onCreate()
        flutterEngine = FlutterEngine(this)
        flutterEngine.dartExecutor.executeDartEntrypoint(
            DartExecutor.DartEntrypoint.createDefault()
        )
        FlutterEngineCache.getInstance().put("my_engine", flutterEngine)
    }
}

跳转时：

kotlin复制val intent = FlutterActivity
    .withCachedEngine("my_engine")
    .build(this)
startActivity(intent)

这个方案的优点是页面秒开，因为 Dart 运行环境已经就绪。缺点是引擎生命周期控制权完全落在原生侧，如果整个 App 只会在一个页面用到 Flutter，那这个引擎会常驻内存。FlutterEngine 常驻内存大概多消耗几十 MB，对大多数 App 来说可以接受，但要在工程文档里记清楚，避免后续另一个同事又创建了一个新引擎。

6.3 FlutterEngineGroup：多入口场景的内存优化

如果 App 里有多个 Flutter 页面，而且每个页面有独立的业务状态，更合适的方式是 FlutterEngineGroup。它允许你在同一个 Dart 运行时上派生多个引擎，共享底层资源，内存增长比完全独立创建多个引擎小得多。

kotlin复制val engineGroup = FlutterEngineGroup(this)

fun createNewEngine(route: String): FlutterEngine {
    val dartEntrypoint = DartExecutor.DartEntrypoint.createDefault()
    val engine = engineGroup.createAndRunEngine(this, dartEntrypoint, listOf(route))
    return engine
}

然后用 FlutterActivity.withNewEngine().build(this) 传进去。EngineGroup 对大多数电商类 App 很合适，因为购物车、商品详情、订单结果都可能用 Flutter 实现，这几个页面并存在返回栈里的情况不少。

6.4 参数传递与返回结果

页面之间传参的规矩：能用 Intent extra 就用 extra，复杂结构用 MethodChannel。

kotlin复制// 原生 -> Flutter
val intent = FlutterActivity
    .withNewEngine()
    .initialRoute("/product/detail?id=10086")
    .build(this)
startActivityForResult(intent, REQUEST_CODE_PRODUCT)

Dart 侧在 main 函数里读取初始路由：

dart复制void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final route = ModalRoute.of(context)?.settings.name ?? '/';
    // 解析 route 里的参数
    return MaterialApp(
      home: ProductDetailPage(route: route),
    );
  }
}

Flutter 返回原生时，调用 SystemNavigator.pop() 只能退出 Activity，没有返回值。正确做法是用 MethodChannel：

kotlin复制// 原生侧注册
flutterEngine.dartExecutor.binaryMessenger.setMessageHandler("app.channel/back.result") { message, reply ->
    val result = mapOf(
        "code" to 0,
        "data" to message.toString()
    )
    setResult(Activity.RESULT_OK, Intent().putExtra("flutter_result", result.toString()))
    finish()
}

这套通讯方式在混合开发里几乎是标配。建议把 channel 名称统一收口在一个常量类里，不要分散写。

7. 调试、生命周期与内存：混合开发真正的硬骨头

7.1 debug 模式下热重载怎么连上

源码依赖集成后，热重载不是天然就能用的。你要在原生 App 启动后，把 Flutter 调试器和 Dart VM 服务连接上。步骤是：先在 Android Studio 或命令行跑 flutter attach，它会扫描设备上正在运行的 Flutter 引擎，连接成功后就能像纯 Flutter 工程一样按 r 热重载。

不过这个流程有个坑：如果 App 是在 release 模式下安装的，Flutter 引擎已经 AOT 编译，flutter attach 连不上。所以平时开发一定要跑 debug 构建：

bash复制./gradlew :app:assembleDebug

或者直接用 Android Studio 的 Run 按钮，确保 Build Variants 里选的是 debug。

7.2 引擎生命周期和页面销毁

FlutterActivity 自带对引擎生命周期的基本管理，但当你手动持有 FlutterEngine 时，就得自己负责销毁。一个比较稳妥的策略是：整 App 只允许存在一个常驻引擎，如果业务复杂度不需要常驻，就在页面 onDestroy 时销毁引擎，下次进入再重建。

kotlin复制override fun onDestroy() {
    if (!isChangingConfigurations) {
        FlutterEngineCache.getInstance().remove("my_engine")
        engine.destroy()
    }
    super.onDestroy()
}

isChangingConfigurations 判断很重要，否则旋转屏幕时会销毁一个正在使用的引擎。这个场景我在实际开发中踩过，旋转屏幕直接黑屏。

多引擎场景下，释放资源更简单：

kotlin复制engineGroup.destroyAllEngines()

但这会同时销毁所有 Flutter 页面，所以别在单个 Activity 的 onDestroy 里调用，应该在 Application 的退出逻辑或所有 Flutter 页面都关闭后的时机调用。

7.3 混合栈与零碎 UI 问题

原生页面和 Flutter 页面互相跳转，返回栈由原生侧管理，这本身没问题。但我在做长链路业务的时候发现，如果 Flutter 页面内部用 Navigator 又 push 了几层，然后原生返回键按下去，会先触发 Flutter 的 Navigator.pop，而不是直接关闭 Activity。用户常常觉得返回逻辑不好用。

解决思路是统一路由：Flutter 内部页面栈控制在两层以内，超过两层就换成新的 FlutterActivity，或者用 PopScope 拦截返回键行为。方案没有统一标准，但一定要让产品经理提前知道，否则验收时会被反复提 bug。

还有两个高频 UI 问题：

第一，Flutter 页面里弹出底部弹窗，弹窗里有 TextField 时，Android 的软键盘会把弹窗顶得乱七八糟。原因在于 Flutter 的 viewInsets 处理和原生 adjustResize 策略叠加。通常解决是把 AndroidManifest 里该 Activity 的 windowSoftInputMode 设为 adjustResize，并保证 Flutter 侧使用 Scaffold 的 resizeToAvoidBottomInset: true。

第二，PlatformView 的体验问题。Flutter 里嵌原生地图、WebView、视频播放器，本质上是原生 View 叠加在 Flutter 纹理上，有些 Android 设备上会出现闪烁或点击穿透。如果只是要展示网页，优先用 webview_flutter 的合成模式；如果必须嵌原生地图，至少要在 targetSdk 33+ 的机型上做一轮真机回归。

8. 打包上线前的安全检查项：签名、ABI、包体、混淆

8.1 签名不是问题，但产物要选对

混合工程打包时，签名由原生壳工程统一处理，Flutter 产物不参与签名。无论用 assembleRelease 还是 bundleRelease，设置签名的方式和以前完全一样。

真正要注意的是 release 构建时必须让 Flutter 的 release 变体参与编译，否则 APK 里打进去的是 debug 引擎，体积大、性能差，有些设备上还会出现明显的卡顿日志。确认方法：构建完成后检查 APK 里的 lib/arm64-v8a/libflutter.so，release 产物会比 debug 小一截，这是 AOT 编译后的引擎。

8.2 ABI 与包体积

Flutter 引擎针对 armeabi-v7a、arm64-v8a、x86_64 都有对应 so。如果你的 App 只在现代手机上运行，可以只保留 arm64-v8a，在 app 的 build.gradle 里配置：

groovy复制defaultConfig {
    ndk {
        abiFilters 'arm64-v8a'
    }
}

这会明显减小包体积。但要注意，如果还有 32 位设备用户，删掉 armeabi-v7a 会导致这些设备无法安装。混合工程引入 Flutter 后，包体积一般会增加 8MB 到 20MB，具体取决于 ABI 数量和 Dart 代码量。如果包体涨幅比这个数字大很多，大概率是 debug 引擎被打进去了。

8.3 混淆和 Dart 代码保护

Android 原生侧混淆按原工程配置执行，Flutter 侧的 Android 代码不需要额外接入 ProGuard，因为它会在构建时生成原生代码映射。

Dart 代码的混淆是另一个体系。如果你担心 release 包里的 Dart 逻辑被反编译，用 Flutter 自带的 --obfuscate 参数：

bash复制flutter build apk --release --obfuscate --split-debug-info=build/symbols

这个参数会把 Dart 代码里的符号名混淆成难以阅读的字符串，同时生成调试符号用于后续排查崩溃。需要注意的是，开了混淆后崩溃栈映射会变复杂，一定要保留好 build/symbols 目录，最好上传到你们的崩溃监控平台关联起来。

9. 高频报错的完整排查链路

9.1 老式 apply 方法升级后的报警

不少老项目从 Flutter 1.x/2.x 升级后，构建时出现类似：

code复制You are applying Flutter's main Gradle plugin imperatively using the apply method...

这个报警的根因是 Flutter 3 之后插件加载机制改成了 plugin-loader 模式，老脚本还在用命令式 apply。排查和修复步骤：

1. 打开根 build.gradle，搜索是否残留 apply from: 开头的 Flutter 相关语句。
2. 打开 settings.gradle，确认是否已有 includeBuild("$flutterSdkPath/packages/flutter_tools/gradle") 和 plugins 块。
3. 把 app_plugin_loader.gradle 之类的老式加载全部移除。
4. 重新同步 Gradle，如果还有报警，检查 Flutter SDK 版本是否过老，必要时升级。

9.2 flutter-plugin-loader 解析失败

报错长这样：

code复制error resolving plugin [id: 'dev.flutter.flutter-plugin-loader', version: '1.0.0']

这个报错我遇到过的原因有几种：Flutter SDK 路径不对、Gradle 仓库源无法访问、插件版本和 Gradle 不兼容。

排查顺序：

1. 先看 local.properties 里的 flutter.sdk 路径指向哪里，确认不是虚拟路径。
2. 确认 settings.gradle 的 pluginManagement 里 includeBuild 在 plugins 之前执行。
3. 检查网络，gradlew --refresh-dependencies 试试能不能拉取。
4. 如果用了镜像源，确认镜像源里有没有 dev.flutter.flutter-plugin-loader 这个插件，有些公共镜像同步不及时。可以临时切回 gradlePluginPortal() 验证。

9.3 构建过程中遇到 CMake 或生成器相关问题

集成 Flutter Module 后，个别开发者会在构建日志里看到：

code复制Flutter CMake error at CMakeLists.txt:3 (project):
  generator Visual Studio 16 2019 could not find any instance of Visual Studio

这类报错通常不是 Android 构建链路本身的问题，而是 Flutter 桌面端或自定义原生代码的 CMake 配置被 Gradle 错误地当成目标平台处理了。你可以先确认是不是真的需要在 Android 上编译 native C++：如果不需要，把 Flutter Module 里所有包含 CMakeLists.txt 的原生插件精简掉；如果需要，在 local.properties 里明确 Android SDK/NDK 路径，并保证 CMake 版本和 NDK 匹配。

9.4 一个通用的问题定位五步法

混合工程的报错链路比纯原生长，因为一次构建会走 Gradle、Flutter 工具链、Android 原生编译三步。遇到问题不要慌，按顺序排查：

1. 先跑 flutter doctor -v 确认 Flutter 环境没问题。
2. 再跑 cd flutter_module && flutter build apk --debug，确认 Flutter 侧能独立构建。
3. 回到原生工程，执行 ./gradlew :app:assembleDebug --stacktrace，看完整堆栈。
4. 如果报错定位在依赖解析，优先检查 settings.gradle 的仓库源和 plugin-loader 配置。
5. 如果报错定位在编译，优先检查 Java/AGP/Flutter 的版本组合。

这个方法我每次排查混合工程问题都用，比在 IDE 里瞎点有效率得多。你按顺序走一遍，大部分问题会在第 2 步或第 4 步被定位出来。

最后说一个我自己的体会：Flutter Module 集成过程中，最难的不是任何一条 Gradle 语法，而是把“原生主导”和“Flutter 独立”这两套思维模式同时装进一个工程里。只要边界划清楚——原生管壳、管路由、管生命周期，Flutter 管页面渲染和交互——后面坑再多，也都是能填平的技术细节。