OpenHarmony版Flutter环境搭建实战：从零到一构建HAP包

先说结论：这一天的训练营内容，就是把“OpenHarmony版Flutter 3.27.4”这套开发环境从零到一跑通。目标很简单——让 Flutter 代码能跑在开源鸿蒙设备上，最终产物不是 APK，而是 OpenHarmony 的 HAP 包。整个环境搭建涉及 DevEco Studio、OpenHarmony SDK、适配版 Flutter SDK、Node.js 和 hvigor 构建工具，链路比纯 Android 开发长一截，但思路理清之后并不复杂。

这篇内容不是训练营官网的图文实录，而是我把 DAY 2 涉及的所有环节重新走了一遍，把每一步“为什么这么做”和“没写进文档的坑”都补全。适合正在跟训练营节奏走的小伙伴，也适合想从原生 ArkUI 转向 Flutter 跨平台方案的开发者。看之前先有一个心理准备：这套环境搭建过程中，90% 的时间不是在写代码，而是在处理版本匹配和下载超时问题。这篇文章争取把你可能踩的坑提前替你踩了。

1. 为什么非要折腾 OpenHarmony 版 Flutter

1.1 开源鸿蒙生态与跨平台需求的现实情况

OpenHarmony 这几年的应用生态其实处于一个很微妙的状态：系统本身在快速迭代，设备形态从开发板、平板到富设备越来越多；但应用侧开发者数量有限，很多团队还在观望。观望的核心原因之一就是——开发语言和框架到底选哪套。

原生 OpenHarmony 应用开发用的是 ArkTS 和 ArkUI 声明式语法，还有 Stage 模型那套东西。如果你从零开始学，精力投入不小。而很多团队手里已经有一批 Flutter 业务代码，想往 OpenHarmony 上迁移。这时候如果 OpenHarmony 只能做原生开发，迁移成本就等于重写一遍业务，绝大多数团队都接受不了。

所以社区里很早就有人在做 Flutter 引擎往 OpenHarmony 上移植的事。到了 Flutter 3.27.4 这一个版本，OpenHarmony 适配分支已经相对成熟，不再是当初“只能跑个 Demo”的玩具状态。它能出 HAP 包，能在 OpenHarmony 模拟器上跑，也能在真机上跑。这就是 DAY 2 训练营存在的意义：先把地基打好。

1.2 原生 ArkUI 与 Flutter 方案怎么选

我先说一个很多学员问过的问题：既然 OpenHarmony 有官方推荐的 ArkUI，为什么还要用 Flutter？

答案不是“谁比谁强”，而是“看团队存量”。ArkUI 的优势在于它是系统原生方案，组件渲染、分布式能力对接都是第一优先级，代码和系统更新同步。Flutter 的优势在于跨平台一致性和生态存量——你的业务逻辑、状态管理、第三方包在 Android、iOS、Web 上已经验证过了，移植到 OpenHarmony 只需要处理渲染层和平台通道。

选型上我自己的判断是：

• 新项目、只做鸿蒙设备：直接用 ArkUI，没必要绕。
• 已有 Flutter 代码仓库、要做鸿蒙版本：用 OpenHarmony 版 Flutter，代码复用率可以到 80% 以上。
• 团队人员技能栈偏 Dart：Flutter 方案学习成本更低，Dart 的 async/await 模型对写业务逻辑比 ArkTS 的装饰器那套更直白。

所以 DEF 2 这一天的训练营，实质上是在帮你回答“我能不能用 Flutter 做鸿蒙应用”这个问题，而答案前置条件就是环境能不能搭起来。

1.3 Flutter 3.27.4 这个版本有什么说法

我特意去查了这个版本对应的仓库分支信息。OpenHarmony 版 Flutter 不是 Google 官方主线发布的版本，而是 OpenHarmony 生态内的适配分支，基于官方 Flutter 3.27.4 打了 OpenHarmony 平台支持补丁，增量维护了若干引擎改动和构建工具链支持。

为什么要强调 3.27.4，而不是随便一个 3.x 版本？因为 OpenHarmony 的 API 演进很快。镜像、权限模型、ability 生命周期都在变，Flutter 适配版本如果落后，构建出来的 HAP 包可能直接跑不起来，或者能跑起来但 API 能力和工程配置对不上。版本这个东西，差一个小版本都可能天差地别，我在后面会专门写一节版本对应关系。

2. 环境准备：先把“地基”打牢

2.1 组件清单与版本对应关系

DAY 2 环境搭建涉及的东西比普通 Flutter 环境多了一层——普通 Flutter 只需要 Flutter SDK、Android SDK、JDK、编辑器；OpenHarmony 版，需要 DevEco Studio、OpenHarmony SDK、Node.js、ohpm 包管理器、hvigor 构建工具，外加 Flutter SDK 本身。

我在具体列配置之前，先给一个目前的推荐组合表。记住这个搭配能省掉后面一半的报错排查时间：

照着这个表装，你大概率能一次过。如果版本交叉（比如 DevEco 4.x + OpenHarmony SDK 9 + Flutter 3.16 分支），构建过程会有各种极其隐蔽的报错，我会在第 5 节展开讲。

2.2 DevEco Studio 与 OpenHarmony SDK 安装

DevEco Studio 本质上是 IntelliJ 平台定制版 IDE，装它的流程类似装 Android Studio。去 OpenHarmony 官网开发者板块下载安装包，Windows 下是一个 exe，macOS 下是 dmg。

安装完成之后第一次启动，它会引导你去下载 OpenHarmony SDK。这一步有两个容易踩的坑：

第一个坑：SDK 组件别只装一个 Platform。很多人只装了最新的 API 版本，结果后面 Flutter 构建报“SDK 不存在/版本不匹配”。建议把 API 12 和 API 13（如果有）都装上，SDK 的 Platform 和 Toolchain 一并勾选。

第二个坑：SDK 路径不要带空格和中文。默认安装路径往往在C:\Users\你的用户名\AppData\Local\OpenHarmony\Sdk，这个路径里的用户名如果是中文，后续 hvigor 解析路径时很容易出诡异问题。我建议手动指定到D:\Dev\OHOS\Sdk这种纯英文无空格的路径，能省很多事。

安装完后检查一下 SDK 目录，里面应该能看到ets、toolchains、oh-uni-package.json等文件。oh-uni-package.json里的apiVersion字段就是当前 OpenHarmony SDK 的版本号，后面配置 Flutter 的时候要用到。

2.3 Node.js 与命令行工具检查

很多人不知道 OpenHarmony 应用构建链里有个 Node.js 依赖。hvigor 是 OpenHarmony 的构建工具，它本身用 Node.js 编写；ohpm 是鸿蒙侧的包管理器，同样跑在 Node.js 上。没有 Node.js，DevEco Studio 打开工程会一直卡在 sync 状态。

所以装完 DevEco Studio 之后，立刻装 Node.js 18 或 20 LTS。装完验证一下：

node -v npm -v

然后确认 ohpm 命令是否可用。DevEco Studio 自带了 ohpm，在它的工具目录里，也可以通过命令行单独安装。如果你是纯命令行流，建议把ohpm和hdc都加入系统 PATH，后面用flutter run -d ohos调试的时候会频繁用到。

这一步还有一个“隐藏任务”：DevEco Studio 内置了一个 Terminal，但这个 Terminal 的环境变量不一定跟你系统用户级 PATH 一致。我的经验是——所有环境变量配置完，直接重开一个全新终端窗口，别在旧窗口里干等，很多“配置了怎么没生效”的问题其实是 shell 环境没有刷新。

3. Flutter SDK 安装与环境变量配置

3.1 获取 OpenHarmony 适配版 Flutter SDK

这是整套环境里最值得注意的地方：OpenHarmony 版 Flutter SDK 不能从 flutter 官网下载。官方主线 Flutter 根本不认识ohos这个平台，也没有flutter build hap这条命令。必须用 OpenHarmony 社区维护的 flutter_flutter 仓库，注意这个仓库的全名和分支。

操作上，我建议用 git clone 而不是下载 zip，因为你后面大概率需要切分支看版本信息：

git clone https://gitee.com/openharmony/flutter_flutter.git cd flutter_flutter git checkout 3.27.4

这里要提示一个细节：这个仓库的 tag 命名可能和官方不完全一致，具体名字有可能是3.27.4-ohos、openharmony-3.27.4或者类似。如果 checkout 没找到对应 tag，先git tag | grep 3.27看看真实命名习惯是什么。

clone 完成之后，把flutter_flutter/bin加入系统 PATH。Windows 上注意加到用户 PATH 的最前面，确保flutter --version显示的是这个 OpenHarmony 适配版，而不是之前在电脑上装的某个官方版本。

验证命令：

flutter --version flutter config --list | grep ohos

如果版本号和分支正确，应该能看到 Flutter 3.27.4 以及 openharmony 相关的配置项。

3.2 环境变量与国内镜像配置

OpenHarmony 版 Flutter 构建时要下载三类依赖：Dart 包（pub.dev 上的）、OpenHarmony 的 ohpm 包、以及 Gradle 构建产物。这三类依赖下载源默认都在海外，直接裸跑会让你怀疑人生。

配置方式分两层。

第一层是 Flutter 侧。把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 指向国内镜像站点。我试过之后建议直接在用户环境变量里设，别只写在项目级配置，因为 Flutter create 阶段就开始要下载依赖了：

export PUB_HOSTED_URL=https://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

Windows 用户对应的系统设置里加同名用户变量即可。

第二层是 ohpm 侧。OpenHarmony 工程的顶层oh-package.json5文件里的注册源如果没改，下载依赖同样慢。可以在工程级配置一个.npmrc，或者直接在 ohpm 全局配置中设置国内注册源。这一点训练营 DAY 2 文档里大概率只是提了一句不展开讲，但实际构建速度差好几倍。

设置完之后别急着建项目，先跑一次：

flutter doctor -v

重点看 log 里有没有OpenHarmony相关的检查项。有的版本 doctor 会把ohos当作独立flutter doctor列表项显示，只要没有红色 X，说明 Flutter 已经能识别到本机 OpenHarmony SDK 了。

3.3 flutter doctor 检查技巧

flutter doctor不是跑一次就完事的命令。在 OpenHarmony 开发场景下，我会习惯性加-v跑，因为它会输出版本断言和各个模块的真实路径，而这些信息在后续排查“hvigor 找不到 / SDK 版本对不上”时非常关键。

跑完 doctor 后，看三行：

• Flutter version：必须显示 3.27.4（OpenHarmony 分支）
• OpenHarmony SDK：路径不能为空，且 API 版本与后面工程一致
• Node.js：版本在 18 以上

如果 doctor 直接报找不到 ohos SDK，别急着重装 Flutter。大概率是环境变量没配对。OpenHarmony 版 Flutter 会读取 DevEco Studio 配置的 SDK 路径，或者读取一个叫OHOS_SDK_HOME的环境变量。把这个变量指向 SDK 根目录（包含ets、toolchains的目录），再次 doctor 一般就过了。

4. 创建项目并运行到模拟器

4.1 从 flutter create 到 OHOS 工程生成

环境变量配置好后，开始创建项目。这一步和官方 Flutter 的区别在于：新版 OpenHarmony 扩展之后，flutter create会额外生成一个ohos目录，这个目录就是 OpenHarmony 侧的应用壳工程。

flutter create my_ohos_app cd my_ohos_app ls

正常情况下能看到android/、ios/、web/、ohos/、lib/这些目录。如果没看到ohos/，说明当前 Flutter SDK 的 OpenHarmony 支持没打开。执行一下：

flutter config --enable-openharmony

然后再重新 create 一个新项目。注意这里有个很容易让人迷茫的点：如果你对同一个目录反复执行flutter create，它可能不会补全缺失的平台目录，最稳妥的做法是新建一个目录重来。

ohos目录内部结构和普通的 OpenHarmony 工程很接近：有AppScope、entry/src/main/ets、build-profile.json5等。Flutter 运行时的入口 engine 是通过 Gradle 插件（ohos侧叫hvigor插件）打进 HAP 里的。很多报错都发生在“代码没问题，但是工程结构不被 hvigor 识别”这个环节。

4.2 用 DevEco Studio 打开鸿蒙侧工程

我实际做过两种方式：一种是用 VS Code 改 Dart 代码，然后用 DevEco Studio 跑构建；另一种是全部在 DevEco Studio 里干。我的体验是——只用 DevEco Studio 最省心。

因为 OpenHarmony 工程的 sync、签名、hap 打包都是在 DevEco Studio 生态里完成的，你用 VS Code 改 Dart，再切回 DevEco Studio 构建，确实可行，但工具链之间没有官方联动，经常出现“Dart 侧改了热更新不了”的情况。

正确姿势：用 DevEco Studio 打开my_ohos_app/ohos目录，而不是打开整个 Flutter 项目根目录。打开的时候 IDE 会识别这是一个 OpenHarmony 工程，并触发一次sync。首次 sync 时间会比较长，因为要把 Flutter engine 的 so 库、ohos 依赖、hvigor 插件一起下载编译。

同步完成后，检查一下工程级local.properties文件，里面应该有两个关键字段：

flutter.sdk=/path/to/openharmony-flutter ohos.sdk.dir=/path/to/ohos-sdk

如果flutter.sdk指向的还是官方 Flutter，立刻改掉，否则构建到一半会报各种找不到flutter_ohos插件的问题。

4.3 构建 HAP 与运行调试

工程配置正确后，运行方式有两种。

第一种：直接在 DevEco Studio 里点 Run。它会把 HAP 安装到已经连接的 OpenHarmony 模拟器或真机上。这是最直观的方式，适合第一次跑通验证。

第二种：命令行方式。先启动模拟器或者在设备上开启 hdc 调试，然后：

flutter build hap --debug

如果只要 debug 跑起来验证，直接：

flutter run -d ohos

这条命令会完成“构建 HAP + 安装 + 启动”整个链路。这里要特别提醒一点：确保你的模拟器已经启动完毕再执行。模拟器在启动过程中，hdc 设备列表不一定能立即发现，flutter run会直接报 no devices found，造成“明明环境没问题但就是跑不起来”的错觉。

跑起来之后你能看到 Flutter 默认计数器 Demo 页面。这时候环境搭建就算真正完成了。我在训练营里反复强调：不要急着删掉这个默认工程，后面学 Flutter 组件通信、状态管理都要拿它做基线。

5. 常见问题排查实录

5.1 flutter run 直接报错跑不起来

这是当天训练营里被问得最多的问题。现象是一执行flutter run -d ohos，立刻报错退出。原因通常不是 Flutter 本身坏了，而是前面某一环没有真正完成。

排查顺序我总结成一个固定的方法，按下面这个顺序来：

1. flutter doctor -v：确认 Flutter 识别到 OpenHarmony SDK
2. hdc list targets：确认模拟器/真机在线
3. 手动打开 DevEco Studio 点一次 Run：确认 HAP 能构建成功

这三步里哪一步出了问题，就回到对应环节去查。尤其是第三步，如果你能在 DevEco Studio 里正常 Run，但命令行跑不起来，那最大嫌疑就是 PATH 或 SDK 路径不一致。用where flutter看看当前 shell 解析到的 flutter 是不是你配置的那个。

5.2 Dart VM 初始化异常（dart_vm_initializer.cc(41)）

训练营当天有学员在模拟器上跑，日志里出现了类似这样的输出：

E/flutter (31173): [ERROR:flutter/runtime/dart_vm_initializer.cc(41)] Unhandled exception

这个报错本身意思是 Dart 侧代码抛了未捕获异常。但为什么会发生在环境搭建 DAY 2？大多数情况不是因为业务代码逻辑错误，而是引擎与设备架构不匹配。

在 OpenHarmony 模拟器上特别容易遇到：模拟器镜像如果是 x86_64，而 Flutter engine 默认构建的是 arm64 版本，跑起来时引擎初始化失败，表现为 dart_vm_initializer 直接崩。解决方式两种：

• 换用与 engine 匹配的模拟器镜像
• 或者用flutter build hap --debug --target-platform ohos-x64这种显式指定架构参数重新构建

我个人的习惯是：第一天跑环境，直接用 arm64 真机，省掉架构匹配的烦恼。模拟器留给后面日常调试 UI 用。

5.3 Gradle 插件冲突与海量依赖下载失败

很多 OpenHarmony Flutter 工程里会残留一份 Android 侧配置。报错信息类似：

You are applying Flutter's main Gradle plugin imperatively using the apply script

这问题本质上是工程根目录的android/子项目被意外执行了，而当前 SDK 是 OpenHarmony 分支，它认识的是ohos平台，不认识这个 gradle 脚本。触发场景通常是你执行了flutter build apk或者 IDE 误触发了 Android 构建。

解决办法就是不要在当前工程跑任何 android 相关构建命令。OpenHarmony 版 Flutter 的构建命令是flutter build hap。如果确实需要同时维护 Android 版本，请另开一个分支目录，不要把两个平台构建挪到一个工作目录里，互相污染配置。

依赖下载失败是另一个高频问题。oh-package.json5里的依赖、以及 flutter pub 缓存，如果下载源没切换，构建时就会卡在Resolving dependencies...状态很久，最终超时。处理方式我前面已经说了：PUB_HOSTED_URL、FLUTTER_STORAGE_BASE_URL、ohpm 注册源三个都换掉，同时在ohos目录下执行一次：

ohpm install --all

把依赖提前拉下来，再回 DevEco Studio 做 sync，速度完全不一样。

5.4 版本不匹配最容易踩的时间坑

我开头给过一个推荐版本表，这里详细解释为什么要严格遵守版本对应。

这就是为什么训练营 DAY 2 没有让大家“装最新版”“装 preview 版”，而是锁死在一个验证过的组合。开源鸿蒙生态里“最新版”往往不等于“最稳版”，版本锁得越死，后续排错越简单。

排查的时候如果拿不准，就去看 Flutter 的适配仓库的 README 或 Release Notes。里面一般有兼容性说明，列出了经过验证的 DevEco Studio 版本和 OpenHarmony SDK 版本。我这套组合也是参照它对出来的，实测最稳。

6. 最后说几个没人明说的操作细节

环境搭完之后，我建议立刻做两件事，都是我踩过坑之后养成的习惯。

第一件事：给 Flutter SDK 目录和 OpenHarmony SDK 目录分别建一个文本文档，记录版本号和安装日期。这听起来很啰嗦，但开源鸿蒙生态迭代太快，可能一周后你同事的电脑上就装了另一个 API 版本。当你们互相看问题的时候，版本号就是第一筛选项，没有版本记录，光是核对环境就要浪费半小时。

第二件事：做一次命令行离线构建验证。具体做法是在ohos目录下执行：

hvigorw clean --no-daemon hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

如果这两条命令能过，说明整个构建链在命令行层面是通的。为什么强调命令行？因为很多人依赖 IDE，一旦 IDE 抽风（比如缓存损坏、索引失效），整个环境就瘫了。命令行通道是最后一道保险。

我在训练营 DAY 2 现场遇到过一位学员，他的环境在 IDE 里一切正常，但命令行构建必挂。查了半天，发现是他的用户 PATH 里有一个很旧的 npm 全局目录，把 hvigor 依赖的 Node.js 给覆盖了。改掉 PATH 顺序之后一切恢复。这类问题没有任何文档会写，只能靠“环境变量逐项检查 + 命令行验证”这一套土办法兜底。

OpenHarmony 版 Flutter 的环境搭建确实比安卓多绕几个弯，但绕完之后你会发现，后面写 Dart 业务代码、调组件、跑热重载，体验和官方 Flutter 几乎没有差别。如果你跟我一样手头有一批存量 Flutter 代码，这套环境就是你跨入开源鸿蒙生态最平滑的入口。先把环境这关过了，DAY 3 的内容才能真正跑起来。