前言
阅读提示（2026-10-30 更新）：本文前半部分是架构演进推演，不是 HarmonyOS NEXT 可直接编译的 Flutter 接入教程。文中的
StageAbility、CustomComponent、FlutterEngine等名称用于解释职责关系，不代表当前 SDK 或社区适配仓中的真实 API；请勿复制代码作为工程实现。
目前可以从 OpenHarmony SIG 的文档与项目索引查看 Flutter 相关仓库，包括 flutter_flutter、Engine、Packages 和 Samples。它们属于社区适配工作，不等同于 Flutter 上游对 HarmonyOS NEXT 的官方支持。具体可用能力、分支和构建步骤应以目标设备、系统 API 版本及所选仓库的 README 为准。HarmonyOS 的 XComponent API 文档可用于了解原生图形组件能力，但不能据此推断某个 Flutter 适配分支一定采用了相同的挂载实现。
本文讨论的是迁移评估和架构边界；作者尚未在 HarmonyOS NEXT 设备上完成本文方案的实机验证，实际经验见文末说明。
1. HarmonyOS NEXT 发生了什么变化？
| 维度 | HarmonyOS 2/3 项目常见情况 | HarmonyOS NEXT 项目常见情况 | 适配时需要核对 |
|---|---|---|---|
| 应用模型 | 可能使用 FA 或 Stage 模型 | 以 Stage 模型和 ArkUI 为主 | 生命周期、窗口与页面容器接入方式 |
| UI 框架 | 既有 Java UI，也有 ArkUI 项目 | ArkUI 声明式 UI | Flutter 页面与原生页面如何组合 |
| 编程接口 | 随系统版本和应用模型而异 | ArkTS 与原生接口按 API 版本提供 | 插件 API、权限和构建工具链是否有对应实现 |
| 图形接入 | 由系统版本和适配方案决定 | 由社区适配仓及设备能力决定 | Engine、渲染 Surface、输入事件的实际实现 |
表格是迁移检查维度，不代表每个 HarmonyOS 2/3 或 NEXT 项目都采用相同结构。
2. Flutter 在 NEXT 的定位
目前应区分 Flutter 上游支持与社区适配：OpenHarmony SIG 有维护 Flutter 相关代码和文档的工作，但团队仍需核对所选分支对系统版本、设备和插件的支持范围。可以从以下方向评估：
- 采用社区 Flutter 适配仓：先验证仓库指定分支、工具链和目标设备，再评估 Engine、Embedder 与插件的覆盖情况。
- 使用 Web 方案：若目标系统提供的 Web 能力满足需求，可评估 Flutter Web 页面；性能、插件能力与离线体验需要按目标设备实测。
- 拆分业务模块：原生 ArkTS 页面与 Flutter 模块的组合方式取决于所选适配仓已实现的生命周期、渲染和通信接口，不应假定通用 Flutter Embedder 可以直接复用。
下文只用示意结构解释方案一可能涉及的职责，不提供可复制的实现代码。
3. 架构演进推演：容器与 Embedder 的职责
以下目录树、类型名和流程均为概念示例，用于说明需要解决的问题。实际项目请以所选社区仓库为准；例如系统原生图形组件的 API 可参考 XComponent 文档，但 Flutter 适配仓如何使用 Surface、窗口和输入事件，应直接查看对应分支源码。
3.1 概念目录结构（非实际仓库布局）
ohos/
├── entry/
│ ├── ets/
│ │ ├── AppStorage.ets
│ │ ├── StageAbility.ets # StageEntryAbility
│ │ └── flutter_bridge/
│ │ ├── FlutterStage.ets # ArkUI 容器，与 Flutter Surface 绑定
│ │ └── channels/
│ │ └── MethodChannel.ets
│ └── src/main/resources/
├── cxx/
│ ├── flutter_stage.cc # 概念示意：原生渲染与事件桥接
│ └── plugins/
└── build-profile.json53.2 Stage 模型入口需要承担的工作
概念上，应用入口需要协调 Flutter 实例的创建、前后台生命周期、路由初始状态和页面容器。实际入口类名、回调签名及 Flutter 实例管理 API 均由适配仓决定，本文不提供伪造的 ArkTS 接口示例。
3.3 渲染容器需要承担的工作
容器层需要把 Flutter 渲染目标接入系统原生窗口或 Surface，并处理尺寸变化、销毁与重建。XComponent 是系统提供的原生组件之一；实际适配仓是否使用它，以及如何连接 Flutter Renderer，必须以仓库代码为准。
3.4 C++ Embedder 要点
Embedder 可能涉及的职责包括：
- 对接所选适配方案的图形 Surface 与 Flutter Renderer。
- 将触控、键盘等系统输入事件转换为 Flutter Engine 支持的事件。
- 按适配仓的要求处理线程、生命周期与资源释放。
Embedder 还需要将系统触控、键盘、窗口尺寸和生命周期事件转换为 Flutter Engine 支持的接口。具体类型、回调和线程模型都与采用的 Engine 分支相关，不能从这份职责列表直接推导出可编译代码。
实际验证时，应分别检查目标设备的图形能力、Engine 分支、编译工具链及 GPU 渲染兼容性。
4. 插件与原生能力的接入
当 Flutter 页面需要调用 ArkTS 原生能力时，插件目录可以按 Dart 接口和平台实现分层组织。下面仍是概念结构，不对应某个特定仓库：
plugins/
├── camera/
│ ├── lib/camera.dart
│ ├── ohos/ets/CameraPlugin.ets
│ └── cxx/camera_plugin.cpp
└── auth/4.1 平台通道的实现边界
Dart 与 ArkTS 之间需要约定消息编码、线程切换、异常返回和生命周期释放。通道对象及调用方式属于适配仓实现细节，应使用仓库中已经提供的 API。
4.2 原生插件的实现边界
每个插件需要对照目标 API 版本实现权限检查、异步结果回传和资源清理。上面提到的文件、相机等能力只是业务方向，不是本文验证过的系统 API 调用示例；实现时应查阅 HarmonyOS 对应版本的官方 API 文档和适配仓源码。
5. 迁移策略与风险控制
5.1 双轨并行策略
| 阶段 | 目标 | 说明 |
|---|---|---|
| T0（现状） | HarmonyOS 2/3 + Flutter | 继续维护存量用户 |
| T1（过渡） | 引入 NEXT 版 Flutter 容器 | 少量机型灰度，验证稳定性 |
| T2（目标） | NEXT 原生能力 + Flutter 混合 | 核心流程 ArkTS，增值业务 Flutter |
5.2 风险点
- 维护边界：明确 Flutter 上游、社区适配仓和业务团队分别负责的部分，以及所选分支的维护状态。
- API 与权限：按目标系统 API 文档实现权限、数据访问和插件能力，并验证发布要求。
- 性能不确定性：对目标设备实测帧率、内存、启动耗时和图形兼容性，准备原生页面或 Web 页面等备选方案。
- 人力结构调整：ArkTS 成为主流，Flutter 团队需补强 ArkTS 能力，或引入双栈人才。
6. 工程实践建议
- 模块化管理：将 Flutter 部分封装为独立模块，通过 ArkTS API 暴露入口，便于替换。
- 接口抽象：所有系统能力先抽象 Dart 接口 + ArkTS 实现，可随时替换为 ArkTS 原生版本。
- 自动化测试：搭建 ArkTS UI 自动化（基于 OpenHarmony TestKit）+ Flutter 集成测试的双套测试体系。
- 可观测性：引入统一日志、性能监控，支持多框架互通。
7. 结论与展望
评估 HarmonyOS NEXT 项目中的 Flutter 方案时，团队需要：
- 学习并掌握 ArkTS/ArkUI，理解与 Flutter 的互补关系。
- 评估社区适配仓的成熟度与维护边界，不预设必须自研 Embedder。
- 在业务层做拆分，区别哪部分必须 ArkTS 原生，哪部分可继续由 Flutter 承担。
后续评估时可关注：
- Flutter 上游与 OpenHarmony 社区的适配进展。
- 目标适配仓对 GPU、输入、插件和系统 API 的支持情况。
- 原生 ArkTS 页面、Flutter 页面与 Web 内容的组合成本。
下一篇《Flutter × OpenHarmony 轻量设备：LiteOS 可行性分析》讨论现有 Flutter OHOS 工具链的支持边界，不提供未经验证的设备适配步骤。
实战案例
我还没有在 HarmonyOS NEXT 设备上实操适配；现有的 HarmonyOS 2 组件工程只能作为旧版经验参考，不能作为 NEXT 构建验证。对存量 Flutter 项目，我会先评估社区适配仓是否覆盖目标设备、系统 API 和所需插件，再决定是否迁移；如果目标系统能力和维护周期更适合 ArkTS 原生开发，也应把原生方案纳入比较。后续有实际设备验证后，再补充可复现的工程步骤与结果。本文的社区仓库和系统组件参考见前言。