Flutter 鸿蒙化进阶：OpenHarmony 性能、插件与发布检查

阅读范围与验证状态

本文讨论使用 OpenHarmony SIG 社区 Flutter 适配 SDK 的工程检查方法。HarmonyOS 商用系统与 OpenHarmony 项目不是可以互换的目标标签；插件能力、配置格式和构建步骤都要按系统 API、应用模型及 flutter_flutter 分支确认。

验证状态：文档核对，未在本次修订中实机复测。 原稿中的 @ohos.distributedObject、MethodChannelManager、featureAbility.continueAbility()、flutter build ohos 和 GitHub Actions 配置没有对应的可复现版本与来源，本次已移除。下面提供的是检查流程，不声称这些步骤已在某个设备或 SDK 版本上运行通过。

1. 先建立可复现的基线

开始性能或兼容性优化前，记录并固定：

OpenHarmony SIG flutter_flutter 的分支或 commit。
对应的 OpenHarmony SDK、DevEco Studio 与 JDK 版本。
目标设备型号、系统版本/API 与应用模型（FA 或 Stage）。
插件依赖版本、构建模式、签名方式和复现步骤。

社区适配仓和 SDK 会更新。CI 不应使用普通 Flutter stable 来代替 OpenHarmony 适配 SDK，也不应使用未经验证的“最新版”组合。将所选 commit 和依赖写入构建环境，按该分支 README 配置环境，再执行 flutter doctor -v。

2. 性能优化先测量，再改代码

在目标设备的 profile 构建上用 Flutter DevTools Performance view 记录典型操作，分别观察 UI 与 raster 线程的帧耗时。60 Hz 屏幕约有 16.7 ms 的帧预算；高刷新率设备的预算更短。该预算用于解释帧时间，不是所有设备的统一验收指标。

定位到具体瓶颈后再选措施：

UI 线程耗时高时，检查 build 期间的同步计算、过大的状态更新范围和布局测量。
Raster 线程耗时高时，检查复杂绘制、透明合成、大面积裁剪和过大的图片纹理。
列表图片内存高时，优先准备接近显示尺寸的图片；必要时使用 cacheWidth / cacheHeight 控制解码尺寸，并用 Inspector 检查 oversized images。
每次只改变一个因素，在相同设备、数据和操作路径下对比优化前后的 profile 结果。

不要把特定 Android 设备的 FPS、GPU 或内存数字直接当成 OpenHarmony 的通用目标，也不要根据一次模拟器运行得出真机性能结论。

3. 检查插件和平台能力

对每个原生能力依赖建立一份覆盖清单：

能力	核对内容
文件、相机、定位、推送等插件	是否有适配目标系统 API 的 OpenHarmony 实现；使用哪个分支和版本
自研 Platform Channel	Dart 与 ArkTS 两端的方法名、参数、异步返回和错误映射是否一致
权限	目标应用模型下的声明文件、权限说明、用户授权时机和拒绝后的降级
生命周期	前后台、页面切换、进程重建时插件资源是否正确创建与释放

Flutter 插件有 Android 实现不表示它具备 OpenHarmony 实现。优先查阅所选社区适配分支的 Samples 和插件源码；具体接口不明确时，不要用推测的 ArkTS 包名或 API 填入示例。

4. 按目标应用模型配置

FA 与 Stage 的配置文件不同：FA 使用 config.json；Stage 项目使用 app.json5 和 module.json5，并按其生成的 UIAbility 入口组织组件。不要在 Stage 示例中使用 FA 的 config.json 字段，也不要把某个模型的生命周期代码当作另一个模型的通用实现。

涉及分布式流转、多设备协同或系统级能力时：

先确认目标系统 API 是否提供该能力，以及当前应用模型是否支持。
在对应 HarmonyOS/OpenHarmony 官方 API 文档中核对权限、配置和生命周期要求。
使用适配仓中与目标 API 版本相匹配的示例或插件；不要把 Android 或旧版 Ability API 名称直接搬到 Stage 工程。
在目标真机上记录授权、成功、拒绝、网络中断和恢复等结果。

关于配置文件的模型差异，可参照华为开发者的 Stage 配置说明与 FA 配置说明。

5. 构建 HAP 与 CI

按所选社区 SDK README 完成工具链配置后，常用构建命令为：

flutter doctor -v
flutter pub get
flutter build hap --debug
flutter build hap --release

CI 需要显式检出并固定 OpenHarmony 适配 SDK 的分支/commit，再安装匹配的 SDK、JDK 与命令行工具；不能只调用会安装上游 Flutter SDK 的通用 Flutter action。构建产物路径、签名步骤和上传方式以该适配分支及 DevEco 配置为准，CI 应保存构建日志、依赖版本和 HAP 校验结果。

6. 发布前验收记录

每次发布至少记录：

Flutter OpenHarmony SDK commit:
OpenHarmony SDK / API:
DevEco Studio:
设备型号与系统 build:
构建模式与签名方式:
验证场景与步骤:
结果 / 未通过项:

依照目标应用市场当前有效的发布规范完成兼容性、稳定性、性能、功耗、安全和 UX 检查。若尚未完成真机验证，应标明“未验证”，不要填写推测的版本、设备或性能数据。