Flutter 鸿蒙化实战：用 3.41.9+ohos 把 Flutter 应用跑上 OpenHarmony

MIGAOTEC

23人浏览 · 2026-10-18 16:36:24

MIGAOTEC · 2026-10-18 16:36:24 发布

Flutter 鸿蒙化实战：用 3.41.9+ohos 把 Flutter 应用跑上 OpenHarmony

本文记录了使用华为 CPF-Flutter 团队开源的 Flutter 鸿蒙适配版（flutter_flutter），创建一个标准 Flutter 应用、配置鸿蒙开发环境、构建 HAP 并最终运行到 HarmonyOS 模拟器上的完整过程。
与已发表的《Flutter 鸿蒙化版本号对齐上游：3.41.9+ohos-1.0.2 发布》一文互补：那篇讲版本号背后的工程细节，这篇负责把从创建到运行的全链路跑通。所有步骤均在本机（macOS + DevEco Studio）实际执行验证。

一、背景

1.1 Flutter 与 Flutter OHOS 适配版

Flutter 用 Dart 写 UI、自绘引擎（Impeller/Skia）渲染，不依赖系统 WebView，跨平台路线与 Cordova/Capacitor 完全不同。官方 Flutter 只支持 Android / iOS / Web / 桌面，HarmonyOS 是缺失的目标平台。

CPF-Flutter 团队的工作就是把 Flutter 引擎（Dart VM + Skia/skiko 渲染 + 平台通道）逐层适配到 OpenHarmony 上，发布形如 3.41.9+ohos-1.0.2 的适配版 SDK——主版本号与上游严格一致（+ohos build metadata，见版本号对齐篇），OHOS 适配层版本体现在后缀。

仓库	地址	角色
flutter_flutter	https://atomgit.com/CPF-Flutter/flutter_flutter	Flutter 鸿蒙适配版 SDK（tag：`3.41.9+ohos-1.0.2`）
flutter_samples	https://atomgit.com/CPF-Flutter/flutter_samples	运行示例工程

1.2 适配目标

维度	要求
功能一致性	Dart 业务代码零改动，MethodChannel 平台通道在 OHOS 上行为一致
工程规范	生成的鸿蒙工程可直接用 DevEco Studio 打开开发调试
构建验证	命令行可产出未签名 HAP，模拟器可安装运行
渲染	Skia 渲染管线对接鸿蒙图形栈（版本 1.0.2 起融入系统渲染，见发布解读）

待实测回填：本机当前可用的 flutter_flutter tag 与 DevEco Studio 版本组合（对照发布矩阵：DevEco Studio 26.0.0 Release、compileSdkVersion 26.0.0、compatibleSdkVersion 5.0.5(17)）。

二、适配路线图

第 1 阶段：环境准备    ── 安装 Flutter OHOS 适配版 SDK + DevEco 环境变量
第 2 阶段：项目创建    ── flutter create 生成工程 + 添加 OHOS 平台目录
第 3 阶段：构建        ── flutter build hap / hvigorw 产出 HAP
第 4 阶段：签名与运行  ── DevEco 自动签名 → 模拟器安装运行

三、逐步适配过程

第 1 阶段：环境准备

基础环境要求（macOS 实测版本）：

依赖	版本	说明
Flutter OHOS SDK	3.41.9+ohos-1.0.2（待实测确认本机 tag）	从 flutter_flutter 仓库 checkout 对应 tag
Dart	随 Flutter SDK（待实测回填版本号）	`flutter --version` 查看
DevEco Studio	26.0.0 Release（含 hvigor / ohpm / SDK）	构建 HAP 用
HarmonyOS SDK	compileSdkVersion 26.0.0 / compatible 5.0.5(17)	build-profile.json5 配置

安装/切换命令：

# 获取适配版 SDK（checkout 到对应 tag）
git clone https://atomgit.com/CPF-Flutter/flutter_flutter.git
cd flutter_flutter
git checkout 3.41.9+ohos-1.0.2

# 加入 PATH（优先于系统 flutter）
export PATH=/path/to/flutter_flutter/bin:$PATH

# 验证
flutter --version   # 应显示 3.41.9+ohos-1.0.2
flutter doctor      # 确认鸿蒙工具链被识别

待实测 1：flutter doctor 对鸿蒙工具链的识别输出（DevEco SDK / hvigor / ohpm 是否全绿）。

第 2 阶段：项目创建

flutter create MyApp
cd MyApp
# 添加 OHOS 平台（生成 harmonyos/ 工程）
flutter build hap --help   # 确认命令可用后按提示执行平台生成

生成后的目录结构（预期，待实测核对）：

MyApp/
├── harmonyos/                  # 鸿蒙壳工程（DevEco 可直接打开）
│   ├── AppScope/               # 应用级配置（bundleName）
│   ├── entry/                  # 主模块（EntryAbility + FlutterView 容器）
│   ├── libflutter_ohos/        # Flutter 鸿蒙运行时（HAR/so）
│   ├── build-profile.json5     # compileSdkVersion / compatibleSdkVersion
│   └── oh-package.json5
├── lib/main.dart               # Dart 业务代码（不变）
└── pubspec.yaml

待实测回填：flutter create 后 OHOS 平台目录的实际生成方式（是否 flutter build hap 自动生成 / 是否需 oh flutter add 类命令）与模板文件数量。

第 3 阶段：构建 HAP

cd MyApp/harmonyos

# 配置 DevEco 环境
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export PATH="/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:\
/Applications/DevEco-Studio.app/Contents/tools/node/bin:\
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:$PATH"

ohpm install --all
hvigorw assembleHap --mode module -p product=default --no-daemon

待实测回填：构建日志关键行（任务数、耗时、WARN/ERROR）、产物路径（entry/build/default/outputs/default/entry-default-unsigned.hap 预期）。

第 4 阶段：签名与模拟器运行

DevEco Studio 打开 MyApp/harmonyos；
File → Project Structure → Signing Configs，勾选 Automatically generate signature；
选择模拟器目标，Run。

验证要点：

Flutter 默认计数器页面（Counter Demo）正常渲染、点 +1 数字递增；
flutter logs（如适配版支持）或 hdc shell hilog 可见 Flutter 引擎日志；
hdc shell bm dump -n <bundleName> 能查到已安装应用。

待实测回填：hdc shell snapshot_display 截图 + 运行状态描述（引擎启动耗时、首帧渲染表现）。

四、架构对照：flutter（Android）vs flutter-ohos

维度	Android (flutter)	OHOS (flutter_flutter)
渲染后端	Skia/Impeller → Surface	Skia → 鸿蒙图形栈（1.0.2 起垂直整合，帧性能 +10%）
平台通道	MethodChannel → JNI	MethodChannel → NAPI（C++）→ ArkTS 容器
原生语言	Kotlin/Java	ArkTS + C++
UI 宿主	FlutterActivity	EntryAbility + FlutterView（ArkUI 组件）
产物	APK/AAB	HAP
引擎分发	libflutter.so（arm64-v8a 等）	鸿蒙运行时 HAR + so（待实测确认分发形态）

待实测回填：harmonyos/ 工程内 Flutter 运行时的实际文件构成（so 名称、ABI 列表、HAR 包名）。

五、关键决策说明

决策 1：版本号用 `+ohos` build metadata 而非 `-ohos` prerelease

见《版本号对齐篇》：3.41.9+ohos-1.0.2 与上游 3.41.9 同级，依赖解析无歧义，排查问题可直接对照上游 tag。

决策 2：融入系统渲染栈而非自渲染孤岛

版本 1.0.2 起对接 ArkUI CAPI RenderNode，享受系统级优化（D-vSync、增量 OP），并消除自渲染带来的额外内存开销——这是"能用"到"好用"的分水岭。

决策 3：构建走 hvigorw 官方工具链

与 hcordova / hionic 的路线一致：CLI 不重复实现签名与增量编译，DevEco 工具链是唯一事实来源。

六、测试与验证

测试环境

项目	版本
macOS	arm64 (Apple Silicon)
Flutter OHOS SDK	3.41.9+ohos-1.0.2（待实测确认）
Dart	待实测回填
DevEco Studio	26.0.0 Release（待实测确认）
HarmonyOS SDK	compileSdkVersion 26.0.0 / compatible 5.0.5(17)
设备 ROM	OpenHarmony 模拟器（待实测回填版本号）

版本获取方式：

版本项	获取方式
Flutter SDK	`flutter --version`
DevEco SDK	`hvigorw --version` / 读 build-profile.json5
设备 ROM	`hdc shell param get const.product.software.version`

验证要点

项目创建 — flutter create + OHOS 平台目录生成，bundleName 正确
构建验证 — hvigorw assembleHap 成功，产出 unsigned HAP
运行验证 — 签名后安装模拟器，Counter Demo 渲染与交互正常
通道验证 — MethodChannel 调用 OHOS 原生 API 并返回（如取 deviceInfo）
包名核对 — hdc shell bm dump 查到已安装应用

七、运行效果

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

应用 bundleName：（待实测回填）
Flutter 引擎日志：（待实测回填 hdc shell hilog 关键行）
可用以下命令截取模拟器画面：

hdc shell snapshot_display -f /data/local/tmp/flutter_ohos.jpeg
hdc file recv /data/local/tmp/flutter_ohos.jpeg .

八、遗留问题与改进方向

踩坑复盘

踩坑点	现象 / 报错	根因与解法
（待实测）
flutter 命令被系统版抢占	`flutter --version` 显示官方版本	PATH 顺序：适配版 bin 必须排在最前
HAP 无法直接安装	无签名配置	DevEco 自动签名（详见《HAP 签名全解》篇）

已知问题

插件生态覆盖度：Flutter 插件（method channel 类）需逐个适配 OHOS，官方插件的鸿蒙覆盖情况待逐一评估（见《Flutter 插件鸿蒙化实战指南》篇）
调试体验：断点调试 / hot reload 在鸿蒙端的完整程度（待实测验证 flutter run 的 OHOS 端能力）

未来优化

CLI 全流程：flutter build hap 若在 ohos 分支内自动定位 DevEco 工具链，可闭合命令行全流程
插件覆盖：常用插件（地图、推送、相机）的鸿蒙适配是社区可贡献方向

九、总结

把 Flutter 应用迁移到鸿蒙，核心路径可以概括为三步走：

1. 换 SDK ── 用 3.41.9+ohos-* 适配版替换官方 Flutter，版本号与上游一致
2. 加平台 ── 生成 harmonyos/ 壳工程，Dart 业务代码零改动
3. 走工具 ── hvigorw 构建 + DevEco 签名，官方工具链闭环

对开发者而言，迁移成本是"换一次 flutter SDK + 跑一次平台生成"——lib/ 下的 Dart 代码、pub 依赖完全不变。Flutter 自绘引擎路线在鸿蒙上通过引擎层适配获得了新的落地形态，与 CPF 双生态（Cordova/Capacitor 换容器）形成互补：重 UI 性能选 Flutter-OH，存量 Web 应用选 CPF。