阅读范围与验证状态
本文聚焦 OpenHarmony SIG 维护的 Flutter 社区适配 SDK 和工程流程。它不是 Flutter 上游自带的平台支持，也不代表所有 HarmonyOS 商用设备、OpenHarmony 发行版或 API 版本都兼容。
验证状态：文档核对，未在本次修订中实机复测。 原稿曾记录一个组件验证工程，但没有留下 Flutter 适配仓分支/提交、系统 API、DevEco Studio 版本和目标设备，无法据此复现本文的具体工具链。下文命令以适配仓和 Samples 文档为准；实际工程应先锁定兼容的 SDK 版本再执行。
1. 先分清应用模型
HarmonyOS 的 FA 与 Stage 是不同的应用模型，配置文件不能混用：
| 项目 | 配置文件 | 入口特点 |
|---|---|---|
| FA 模型 | config.json | 使用 FA 模型的 Ability 配置 |
| Stage 模型 | app.json5、module.json5 | 使用 Stage 组件模型；常见 UI 入口为 UIAbility，ArkTS 页面通常位于 entry/src/main/ets/ |
华为开发者文档分别说明了 Stage 模型配置文件 和 FA 模型配置文件。因此，不能把 config.json、Stage UIAbility 和一套未注明来源的 Flutter 引擎封装拼成通用工程示例。本文旧版中的 FlutterEngineManager、FlutterBoostEngine 和 flutter-harmony create 示例已移除；它们不是 OpenHarmony SIG 当前通用入门流程。
2. 准备匹配的 Flutter 与 OpenHarmony 工具链
OpenHarmony SIG 的 flutter_flutter 仓库是对 Flutter 工具链的社区扩展。具体支持的 SDK、分支和 Engine 产物会变化，开始前应：
- 按所选
flutter_flutter分支的 README 安装对应 Flutter SDK。 - 按该分支要求安装 OpenHarmony SDK、DevEco Studio、JDK 和命令行工具。
- 使用
flutter doctor -v检查 Flutter 与 OpenHarmony 工具链是否都已识别。 - 记录仓库 URL、分支或 commit、系统 API 与 DevEco Studio 版本，方便复现构建结果。
不要把普通 Flutter stable 版本号直接当作 OpenHarmony 兼容版本。版本配对和本地 Engine 要求以当前适配仓的 README 为准。
3. 创建 OpenHarmony Flutter 工程
在配置好社区适配 SDK 的终端中创建新工程：
flutter create --platforms ohos --org com.example flutter_harmony_app
cd flutter_harmony_app
flutter pub get若要给已有 Flutter 工程增加 OpenHarmony 平台目录，应先确认所选分支 README 中对应的创建/迁移方式，再在工程根目录执行；不要把不同版本的脚手架命令混用。
适配工具会生成 ohos/ 工程和相应的嵌入层文件。具体目录、Ability 入口以及签名配置以生成结果和匹配的 flutter_samples 文档为准。ArkTS 页面入口、Stage/FA 配置和 Flutter Embedder 属于不同层次，新增平台时应保留模板生成的依赖关系，不要照抄其他分支的文件树或手写虚构的 Engine 管理 API。
4. 检查插件与系统能力
Flutter 插件能在 Android 或 iOS 工作，不代表它自动具备 OpenHarmony 实现。逐项检查 pubspec.yaml 中的依赖：
- 检查包本身或其维护分支是否包含 OpenHarmony 平台实现。
- 对相机、文件、定位、推送等原生能力，核对目标系统 API、权限声明和插件实现版本。
- 缺少平台实现时，选择维护中的 OpenHarmony 插件、维护自己的适配分支，或提供清楚的降级方案。
- MethodChannel 的两端协议、插件注册方式和生命周期应跟随所选适配仓的 Samples；不要把伪代码当成可以编译的 ArkTS API。
插件清单可按“已适配 / 需替换 / 尚未验证”标注，避免把 Android 插件覆盖率误当成鸿蒙覆盖率。
5. 构建和运行 HAP
OpenHarmony SIG Flutter 工具链使用 HAP 构建命令：
flutter doctor -v
flutter devices
flutter build hap --debug
flutter build hap --release连接设备后可按适配仓文档使用 flutter run -d <deviceId>，或通过 hdc 安装构建产物。Samples 文档给出的常见产物位置为 ohos/entry/build/default/outputs/default/entry-default-signed.hap；不同分支、签名和构建变体可能改变输出路径，应以本次构建日志为准。
6. 适配验收清单
- 工具链版本与
flutter_flutter分支要求一致，flutter doctor -v无缺项。 - Debug 与 Release HAP 都能按目标设备完成构建和安装。
- 前后台切换、窗口显示和应用退出在目标设备上实际验证。
- 所需插件逐项验证；未适配项有替代方案或明确限制。
- 权限、签名和发布检查遵循目标系统版本的官方要求。
- 性能结论在明确设备和构建模式下测量，不以模拟器结果代替真机结论。
参考资料
- OpenHarmony SIG Flutter SDK README
- OpenHarmony SIG Flutter Samples 与文档
- 华为开发者文档：Stage 模型应用配置文件
- 华为开发者文档：FA 模型应用配置文件
页面 URL 保留原有系列地址；文章标题和适配范围已改为与当前文中引用的社区工程流程一致。
下一篇讨论性能、插件和发布前检查；涉及具体系统 API 时，应以目标 API 版本及对应社区适配仓的实现为准。