Android 接入 Flutter（Add-to-App）最小闭环：10 分钟跑起第一个混合页面

上一篇我们解决的是认知问题：

FlutterEngine 是什么？

为什么单引擎会"串页面"？

多模块和多引擎到底什么关系？

这一篇开始真正落地：

👉 在一个已有 Android 项目中，用标准 Add-to-App 方式接入 Flutter，并跑通最小闭环。

目标只有一个：
原生页面 → 打开 Flutter 页面 → Flutter 正常渲染。

一、整体结构先看清（非常重要）

混合开发不是"往 Android 里塞个 Flutter 页面"，而是：

👉 Android 主工程 + Flutter Module

结构类似：

复制代码

project_root/
  android_app/        # 原生主工程
  flutter_module/     # Flutter 模块（被嵌入）

Android 永远是宿主，Flutter 是被加载的运行模块。

二、创建 Flutter Module

在项目同级目录执行：

复制代码

flutter create -t module flutter_module

你会得到一个标准 flutter module：

Dart 复制代码

flutter_module/
  lib/main.dart
  pubspec.yaml
  .android/
  .ios/

此时你已经有了一套可被嵌入的 Flutter 产物。

三、Android 引入 Flutter Module（Add-to-App）

这一块根据工程结构不同，方式会略有差异，但目标只有一个：

👉 让 Android 工程能依赖 flutter_module 产物并编译通过。

完成标志是：

Android 工程 sync 成功
可以引用 Flutter 相关类（FlutterActivity / FlutterEngine）

到这一步，不写一行业务代码，也算成功了一半。

四、Flutter 侧：准备一个可识别页面

flutter_module/lib/main.dart，先写一个最简单页面：

有 main()
有 MaterialApp
有一个明显的 Flutter 文本

目标很纯粹：

👉 确保你看到的确实是 Flutter 在渲染。

比如：

页面写一个 Text("Hello from Flutter")
背景用一个明显颜色

五、Android 侧：最小闭环 ------ 打开 Flutter 页面

在任意一个原生 Activity 里，先做最简单的一步：

👉 打开 FlutterActivity。

逻辑只有一句：

点击按钮
启动 FlutterActivity

完成后你应该能看到 Flutter 页面全屏显示。

这一步成功，代表三件事都通了：

✅ Android 工程集成 OK

✅ Flutter Module 构建 OK

✅ Android ↔ Flutter 渲染链路 OK

六、到这里还不够：必须立刻升级为"单引擎模型"

很多教程到这里就停了，但真实项目绝对不能止步于此。

原因很简单：

默认 FlutterActivity 会：

👉 每次启动都 new 一个 FlutterEngine。

这在真实项目中会带来：

首帧慢
内存增长
页面切换抖动
多 Flutter 页面时不可控

所以正确姿势是：

👉 Application 里预热 + 缓存一个 FlutterEngine。

七、Application 中预热并缓存 FlutterEngine

在你的 Application 中做三件事：

创建 FlutterEngine
执行 Dart 入口
放入 FlutterEngineCache

这一刻，你的 App 里已经常驻了一套 Flutter 运行时。

此后所有 Flutter 页面，都从缓存中拿引擎。

八、用"缓存引擎"启动 Flutter 页面

不要再直接 new FlutterActivity。

而是使用：

👉 withCachedEngine("engine_id")

这样启动的 FlutterActivity：

不会创建新引擎
不会重新启动 Dart VM
几乎是"秒开"

到这里，你的混合工程已经进入"工程级可用状态"。

九、阶段性架构总结（这一步非常关键）

现在你的系统结构已经变成：

Android Application

→ 初始化 FlutterEngine

→ Dart main() 已运行

→ FlutterEngineCache 持有引擎

原生页面需要 Flutter 时：

→ 使用缓存引擎打开 FlutterActivity

→ FlutterActivity 只是"一个显示窗口"

→ 真正的系统在 FlutterEngine 中

这一步完成，你已经具备：

✅ 单引擎模型

✅ Flutter 运行时常驻

✅ 后续可支持 FlutterView 嵌入

✅ 后续可支持多模块路由控制

十、这一篇你应该真正收获什么？

不是"学会了一个 API"，而是三点工程认知：

FlutterEngine 必须前置管理
FlutterActivity 本质只是一个容器
混合项目从第一天就要按"长期共存系统"设计