Flutter OHOS 环境搭建实战:oh-3.44.9-dev 从 0 到 1 完整记录
本文记录了在 macOS(Apple Silicon)上从零搭建 OpenHarmony 版 Flutter SDK(
CPF-Flutter/flutter_flutter仓库oh-3.44.9-dev分支)的完整过程,包含拉取分支、首次初始化、以及过程中遇到的三个典型坑的定位与解决思路。所有命令均在本机真实执行过,附有原始输出供对照。
目录
- 背景:为什么需要这个分支
- 动手前:环境检查清单
- [拉取分支:clone 与仓库结构](#拉取分支:clone 与仓库结构)
- [首次初始化:Dart SDK、precache 与 doctor](#首次初始化:Dart SDK、precache 与 doctor)
- [踩坑①:版本号显示 0.0.0-unknown](#踩坑①:版本号显示 0.0.0-unknown)
- [踩坑②:fvm 报 Invalid Flutter URL](#踩坑②:fvm 报 Invalid Flutter URL)
- [踩坑③:PATH 优先级与"删除旧目录"的乌龙](#踩坑③:PATH 优先级与“删除旧目录”的乌龙)
- 最终验证与日常使用方式
- 经验总结与常见问题速查
1. 背景:为什么需要这个分支
Flutter 官方 SDK 默认只支持 Android / iOS / Web / 桌面端,不包含 OpenHarmony(鸿蒙)平台。要在鸿蒙设备上跑 Flutter 应用,需要社区移植版 Flutter SDK 与配套的 Flutter Engine。
CPF-Flutter/flutter_flutter(CPF 即 Community-Ported Flutter,开源鸿蒙跨平台框架社区)就是这样一个移植仓库:
- 基于 Flutter 官方 3.44.9 版本适配 OpenHarmony;
- Flutter SDK 与 Engine 源码已合并到一个仓库 (
engine/目录),无需再单独克隆 Engine; - 官方稳定版以
3.44.9-ohos-X.X.X形式的 tag 发布;oh-3.44.9-dev则是 3.44.9 对应的开发分支,适合尝鲜和跟进最新修复。
注意:该仓库是从旧的
openharmony-tpc/flutter_flutter(托管在 gitcode)整体迁移 到新组织CPF-Flutter(托管在 atomgit)的,旧仓库已停止维护。README 顶部有迁移公告,克隆时务必使用新地址,并同步更新本地所有引用了旧地址的配置(本文第 6 章就是被旧地址坑到的实例)。
本次任务目标:把 oh-3.44.9-dev 分支安装到本机 fvm 的版本缓存目录(~/fvm/versions/)下,初始化完成后可用 flutter 命令开发鸿蒙应用。
2. 动手前:环境检查清单
安装前先花一分钟确认本机基础条件,避免克隆到一半才发现问题:
bash
# 1. 版本管理工具 fvm(可选,本文用它的 versions 目录统一管理 SDK)
which fvm && fvm --version
# /opt/homebrew/bin/fvm
# 3.2.1
# 2. git
git --version
# git version 2.39.5
# 3. 磁盘剩余空间(Flutter 仓库 + 产物缓存预计占用 1.5~3 GB)
df -h ~/fvm | tail -1
# 460Gi 总容量,剩余 64Gi,充足
# 4. 确认能连上代码托管平台的 SSH
ssh -T git@atomgit.com
# remote: Welcome to GitCode, jianguoxu
两个小观察:
- SSH 握手虽然连的是 atomgit,但服务端欢迎语还显示
GitCode------这是平台品牌迁移期的正常现象,不影响使用; - 本机磁盘剩余空间充足,所以后面补拉完整 git 历史(第 5 章)不会遇到空间问题;如果磁盘紧张,建议先清理再动手。
同时确认 fvm 的版本缓存目录现状(本文会话的工作目录就在 ~/fvm/versions,目前是空的):
bash
ls ~/fvm/versions/
# .DS_Store (空目录,等待新 SDK 入住)
3. 拉取分支:clone 与仓库结构
3.1 克隆命令
AtomGit 官方 Flutter 仓库体积巨大(全量历史可达数 GB),而 fork 分支历史更长,所以首轮克隆建议浅克隆 + 单分支,速度最快:
bash
cd ~/fvm/versions
git clone --depth 1 --single-branch --branch oh-3.44.9-dev \
git@atomgit.com:CPF-Flutter/flutter_flutter.git oh-3.44.9-dev
# Cloning into 'oh-3.44.9-dev'...
# Updating files: 100% (17385/17385), done.
目录名取 oh-3.44.9-dev,正好与分支名一致,也方便 fvm 识别。
3.2 验证克隆结果
bash
cd oh-3.44.9-dev
git branch --show-current # oh-3.44.9-dev
git log -1 --format='%H %s' # 4f1a4267afdd... !1930 merge oh-3.44.9-dev into oh-3.44.9-dev
3.3 仓库结构速览
这是 OpenHarmony 移植版,和官方仓库有明显差异:
oh-3.44.9-dev/
├── engine/ # Flutter Engine 源码(已合入,官方仓库不在此处)
├── packages/ # Flutter SDK 框架代码(flutter / flutter_tools 等)
├── bin/
│ └── internal/
│ ├── engine.version # 通用 Engine 版本
│ ├── engine.ohos.version # OHOS 专用 Engine 版本
│ ├── engine.ohos.har.version # OHOS HAR 产物版本
│ └── update_dart_sdk.sh # Dart SDK 下载脚本(走华为云 OBS)
├── CHANGELOG_OHOS.md # 鸿蒙化变更日志
├── DEPS_ohos # 鸿蒙化依赖
└── README.md # 含迁移公告、版本规划、FAQ
关键发现:bin/internal/update_dart_sdk.sh 里 Dart SDK 的下载地址默认指向
FLUTTER_OHOS_STORAGE_BASE_URL=${FLUTTER_OHOS_STORAGE_BASE_URL:-https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com}
也就是说这个 fork 不需要你手动配置镜像,Dart SDK 会从华为云 OBS 自动下载------这对国内网络非常友好,也是与官方仓库体验差异最大的一点。
另外一个值得留意的细节:README 的版本规划表显示鸿蒙化的节奏大约是上游发布后 4 个月跟上(如 3.44 于 2026-05 上游发布,2026-09 出鸿蒙版),选择分支时可以按这个节奏预判。
4. 首次初始化:Dart SDK、precache 与 doctor
4.1 首次运行 flutter --version:自动下载 Dart SDK
克隆完成后 SDK 还不能直接用------Flutter 工具链首次运行会触发 Dart SDK 下载、依赖解析和工具链自编译。这一步是后续所有命令的基础:
bash
cd ~/fvm/versions/oh-3.44.9-dev
bin/flutter --version
关键输出(约 1 分 08 秒完成):
Downloading Darwin arm64 Dart SDK from Flutter engine 10a8d012d86cd7ee13e0acc859fea796c8a01764...
dart-sdk-url: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/...
% Total % Received % Xferd Average Speed Time Time Time Current
100 197M 100 197M 0 0 7905k 0 0:00:25 0:0:25 --:--:-- 7798k
Building flutter tool...
Resolving dependencies...
Flutter assets will be downloaded from https://storage.flutter-io.cn. Make sure you trust this source!
Flutter • channel [user-branch] • git@atomgit.com:CPF-Flutter/flutter_flutter.git
Framework • revision 4f1a4267af (3 hours ago) • 2026-09-03 19:00:10 +0800
Engine • hash b9499e4c25212536ba3a4eec4f5c1905fb3214fe (revision 5a2a6a42cc) (1 months ago)
Tools • Dart 3.12.2 • DevTools 2.57.0
三个值得记录的细节:
- Dart SDK 走华为云 OBS (
flutter-ohos.obs.cn-south-1.myhuaweicloud.com),197 MB 约 25 秒拉完,国内直连无压力,不需要科学上网; - assets 走
storage.flutter-io.cn------这是本机FLUTTER_STORAGE_BASE_URL环境变量配置的国内镜像,官方默认是storage.googleapis.com; - 此时输出显示的是
channel [user-branch],但没有版本号------这正是第 5 章的伏笔。
4.2 flutter precache --ohos:预下载 Engine 产物
这个 fork 的 precache 专门支持了 --ohos 平台参数(官方版没有):
bash
bin/flutter precache --ohos
输出(约 34 秒)会按 target 逐个下载:ohos-x64-profile / ohos-x64-release、sky_engine、flutter_gpu、flutter_patched_sdk(_product)、darwin-arm64、iOS USB 调试工具链、font-subset 等。执行完,构建 hap 包所需的引擎产物就已就绪。
4.3 flutter doctor:环境体检
bash
bin/flutter doctor
[!] Flutter (Channel [user-branch], 0.0.0-unknown, on macOS 26.6.1 ...)
! Flutter version 0.0.0-unknown on channel [user-branch] ...
Cannot resolve current version, possibly due to local changes.
! The flutter binary is not on your path.
! The dart binary is not on your path.
! Upstream repository git@atomgit.com:CPF-Flutter/flutter_flutter.git is not the same as FLUTTER_GIT_URL
[✓] HarmonyOS toolchain - develop for HarmonyOS devices
[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0-rc1)
[!] Xcode - develop for iOS and macOS (Xcode 16.3)
[✓] Chrome - develop for the web
[✓] Proxy Configuration
[✓] Connected device (2 available)
[✓] Network resources
结论:核心链路全部就绪 (HarmonyOS 工具链 ✓、Android ✓、网络 ✓,Xcode 的警告只是模拟器运行时获取失败,与鸿蒙开发无关),但 Flutter 本体有一条刺眼的警告------版本解析失败,0.0.0-unknown。这就是第一个要解决的坑。
5. 踩坑①:版本号显示 0.0.0-unknown
5.1 现象
flutter doctor里 Flutter 一行显示0.0.0-unknown,提示Cannot resolve current version;bin/cache/flutter.version.json中frameworkVersion与flutterVersion均为0.0.0-unknown;- 顺带影响 fvm:
fvm list里该版本显示为Need setup(fvm 需要靠版本号识别 SDK)。
5.2 原因定位
两件事叠加导致:
- 浅克隆没有 tag :第 3 章用了
--depth 1,克隆下来git tag数量为 0。Flutter 工具链 stamp 版本号时依赖git describe找最近的 tag,没有 tag 就解析失败,回退成0.0.0-unknown; - 版本 stamp 是一次性的 :首次运行生成的
bin/cache/flutter.version.json带有"版本没变就不重算"的缓存逻辑,所以后面即使补了 tag,只要不删这个文件,它仍会沿用旧的0.0.0-unknown。
5.3 解决方案
bash
# 第一步:补全 git 历史与 tags。--filter=blob:none 只拉 commit/tree 元数据、跳过历史 blob,大幅减小体积
git fetch origin --unshallow --filter=blob:none --tags
# 1m10s,拉回 94 个 tag(3.7.12-ohos-1.1.x、3.22.x、3.27.x、github.com/flutter/flutter.git/3.32.4 等)
# 第二步:删除一次性版本缓存,强制重新 stamp
rm -f bin/cache/flutter.version.json
# 第三步:重新运行触发重算
bin/flutter --version
最终输出恢复正常:
Flutter 3.44.9+ohos-0.0.1-canary1 • channel [user-branch] • git@atomgit.com:CPF-Flutter/flutter_flutter.git
bin/cache/flutter.version.json 重新生成后,frameworkVersion = 3.44.9+ohos-0.0.1-canary1,doctor 里的版本警告消失。
5.4 方法论小结
浅克隆省的是下载时间,丢的是"版本溯源能力"。 对需要精准版本号/升级能力的 Flutter fork 环境,建议:先
--depth 1快速落地验证可用性,再按需--unshallow;补历史时用--filter=blob:none控制体积;缓存类文件(stamp、artifacts)出问题时优先考虑删除重建,而不是改代码。
6. 踩坑②:fvm 报 Invalid Flutter URL
6.1 现象
SDK 明明装好了,想用 fvm 把它登记到项目里(fvm use oh-3.44.9-dev),结果报错:
✗ Invalid Flutter URL: "git@gitcode.com:openharmony-tpc/flutter_flutter.git".
Please change config to a valid git url
最诡异的是:git remote -v 里明明写的是 git@atomgit.com:CPF-Flutter/flutter_flutter.git,fvm 却报了一个 gitcode 的旧地址。
6.2 原因定位(双重叠加)
原因 A:~/.zshrc 里残留了迁移前的旧地址。
bash
grep -n "FLUTTER_GIT_URL" ~/.zshrc
# 9:export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git
fvm 会读取 FLUTTER_GIT_URL 环境变量作为"Flutter 仓库地址"参与 URL 校验。这个值还是仓库迁移前(openharmony-tpc 组织、gitcode 平台)的旧地址,自然与现在的 atomgit 新仓库对不上。
原因 B:FVM 不认 git@host:path 这种 scp 简写。
FVM 用 Dart 的 Uri 解析 URL,git@gitcode.com:xxx.git 这种省略协议头的写法在 Dart URI 规范里不是合法 URL。实验记录如下:
| 尝试的 FLUTTER_GIT_URL | 结果 |
|---|---|
git@gitcode.com:openharmony-tpc/flutter_flutter.git |
✗ Invalid Flutter URL(scp 简写 + 旧地址) |
git@atomgit.com:CPF-Flutter/flutter_flutter.git |
✗ Invalid Flutter URL(即使是新地址,scp 简写仍被拒) |
ssh://git@atomgit.com/CPF-Flutter/flutter_flutter.git |
✓ 通过 URL 校验(但后续 fvm use 把名字当官方版本联网安装,非交互环境下卡住超时) |
结论:必须用带协议头的完整 URI 形式 (ssh://git@host/path/repo.git 或 https://...),fvm 才能识别。
6.3 解决方案
与用户确认后,把 ~/.zshrc 更新为新仓库的标准 URI 形式:
bash
export FLUTTER_GIT_URL=ssh://git@atomgit.com/CPF-Flutter/flutter_flutter.git
6.4 顺带澄清:fvm 与手动放入的 SDK
最终验证还发现一个规律:fvm use 不适用于手动放入 versions 目录的 SDK------它会把名字当作官方版本去尝试联网安装/交互确认,非交互环境直接挂起。fvm 官方支持自定义 fork 的方式是:
bash
fvm fork add <别名> ssh://git@atomgit.com/CPF-Flutter/flutter_flutter.git
fvm use <别名> # 或 fvm install <别名>
代价是要按 fvm 的流程重新完整克隆一份。如果只是想让本机这套 SDK 立刻能用,直接走 PATH / 绝对路径即可(见第 8 章),不必非得经过 fvm。
7. 踩坑③:PATH 优先级与"删除旧目录"的乌龙
7.1 需求:让新 SDK 成为默认 flutter
本机 .zshrc 里还有一行旧 flutter 的 PATH(指向 ~/Desktop/harmony/flutter/flutter_flutter/bin)。PATH 拼接规则是后 export 的排前面,所以把新 SDK 放到旧行之后即可压过它:
bash
# 插入后效果(位于旧 flutter 行之后)
export PATH=/Users/jianguo/Desktop/harmony/flutter/flutter_flutter/bin:$PATH
export PATH="/Users/jianguo/fvm/versions/oh-3.44.9-dev/bin:$PATH"
插入前先确认后面不会再出现抢优先级的同名命令:
bash
ls ~/bin/flutter* # (无)
ls /opt/homebrew/bin/flutter* # (无)
grep -l flutter ~/Desktop/cangjie/cangjie/envsetup.sh # (无)
模拟新终端验证:
bash
zsh -c 'source ~/.zshrc; command -v flutter; flutter --version | head -1'
# /Users/jianguo/fvm/versions/oh-3.44.9-dev/bin/flutter
# Flutter 3.44.9+ohos-0.0.1-canary1
7.2 反转:要删的旧目录根本不存在
用户随后要求删除旧的 ~/Desktop/harmony/flutter。检查结果出乎意料:
bash
ls ~/Desktop/harmony/ # (harmony 目录不存在)
find ~/Desktop -maxdepth 3 -type d -iname "*flutter*"
# /Users/jianguo/Desktop/gitcode/深圳公司/flutter ← 投标资料目录,不是 SDK
# /Users/jianguo/Desktop/harmonyos/demo/flutterdemo ← demo 项目,不是 SDK
# /Users/jianguo/Desktop/个人/鸿蒙Flutter开发实践(48) ← 文档目录,不是 SDK
那条 PATH 是历史遗留的失效引用 ,指向的目录根本不存在(也没有 bin/flutter)。于是"删除"变成了"清理引用":
- 删掉
.zshrc中失效的旧 PATH 行; - 用干净环境(
env -i清空继承的 PATH + 登录 shell 重新 source)做最终验证:
bash
env -i HOME="$HOME" TERM="$TERM" zsh -l -c \
'source ~/.zshrc >/dev/null 2>&1; command -v flutter; echo $PATH | tr ":" "\n" | grep -c "Desktop/harmony/flutter"'
# /Users/jianguo/fvm/versions/oh-3.44.9-dev/bin/flutter
# 0 ← 旧路径引用彻底清零
7.3 方法论小结
删除前先核实"目标是否存在" :命令行里看到的 PATH 未必对应真实目录,可能只是历史配置的残留;验证环境要够干净 :普通
zsh -c会继承外层进程的旧 PATH,容易给出误导结果,env -i才是"新终端"的等价模拟。
8. 最终验证与日常使用方式
8.1 最终环境状态
| 项 | 值 |
|---|---|
| SDK 路径 | ~/fvm/versions/oh-3.44.9-dev |
| 版本 | Flutter 3.44.9+ohos-0.0.1-canary1 · Dart 3.12.2 · DevTools 2.57.0 |
| 分支/提交 | oh-3.44.9-dev @ 4f1a4267af |
| git 历史 | 已补全(94 个 tag,blob:none 过滤) |
| 产物缓存 | Dart SDK + ohos 全 target engine 产物(约 1.3 GB) |
| flutter doctor | HarmonyOS ✓ / Android ✓ / Chrome ✓ / 网络 ✓ |
| fvm list | 可识别目录(oh-3.44.9-dev) |
8.2 日常使用三种姿势
bash
# 姿势一:PATH(已在 .zshrc 配置,新终端直接生效)
flutter --version
# 姿势二:项目内用绝对路径(不污染全局)
/Users/jianguo/fvm/versions/oh-3.44.9-dev/bin/flutter pub get
/Users/jianguo/fvm/versions/oh-3.44.9-dev/bin/flutter build hap --debug
# 姿势三:fvm 官方 fork 流程(需要重新克隆,按需使用)
fvm fork add ohos ssh://git@atomgit.com/CPF-Flutter/flutter_flutter.git
fvm use ohos
8.3 创建并运行第一个鸿蒙 Flutter 应用
bash
flutter create --platforms ohos --org com.example my_app
cd my_app
flutter doctor # 确认 HarmonyOS toolchain 就绪
flutter run # 连接鸿蒙设备/模拟器运行
flutter build hap --release # 打 hap 包
9. 经验总结与常见问题速查
9.1 经验总结(五条)
- 认准迁移后的仓库 :OpenHarmony 版 Flutter 已整体迁到
CPF-Flutter组织(atomgit),旧的openharmony-tpc仓库停更;稳定开发优先选 tag(3.44.9-ohos-X.X.X),跟进最新修复用oh-3.44.9-dev这类 dev 分支。 - 国内网络很友好 :Dart SDK 走华为云 OBS(
flutter-ohos.obs.cn-south-1.myhuaweicloud.com),assets 走storage.flutter-io.cn,全程无需代理;但注意切换FLUTTER_STORAGE_BASE_URL后要删<flutter>/bin/cache并flutter clean。 - 浅克隆省时间、丢溯源 :
--depth 1快速落地 → 用--unshallow --filter=blob:none --tags补全历史(体积可控)→ 删bin/cache/flutter.version.json强制重新 stamp,版本号即可恢复。 - fvm 只认带协议头的 URI :
ssh://git@host/path.git或https://...,scp 简写一律报Invalid Flutter URL;FLUTTER_GIT_URL等配置务必同步更新为迁移后地址;手动放入 versions 目录的 SDK 别用fvm use,走 PATH 或fvm fork add官方流程。 - 排查环境要"干净验证" :
env -i+ 登录 shell 才能模拟真实新终端;删除目录前先确认目标真实存在,避免被 PATH 里的失效引用误导。
9.2 常见问题速查表
| 现象 | 原因 | 解决 |
|---|---|---|
Flutter version 0.0.0-unknown |
浅克隆无 tag;stamp 缓存未重算 | git fetch --unshallow --filter=blob:none --tags + 删 bin/cache/flutter.version.json 重建 |
fvm 报 Invalid Flutter URL |
scp 简写 URL;FLUTTER_GIT_URL 指向迁移前旧地址 |
改用 ssh://git@host/path.git,更新 ~/.zshrc 中的 FLUTTER_GIT_URL |
fvm use 卡住/超时 |
手动放入的 SDK 被当成官方版本尝试联网安装 | 改用 PATH 直用,或 fvm fork add <别名> <URI> 官方流程 |
| 切换镜像后下载报错 | FLUTTER_STORAGE_BASE_URL 变更后缓存未清 |
删 <flutter>/bin/cache + 项目内 flutter clean |
The SDK license agreement is not accepted |
鸿蒙 SDK 许可未接受 | ohsdkmgr install ets:9 js:9 native:9 previewer:9 toolchains:9 --accept-license |
The hvigor depends on the npmrc file |
未配置 npm 源 | 用户目录创建 .npmrc(参考 DevEco 官方环境配置文档) |
安装报 fail to verify pkcs7 file |
设备证书校验失败 | hdc shell param set persist.bms.ohCert.verify true |
DevEco Beta 报 compatibleSdkVersion 缺失 |
Beta 版配置校验更严格 | 按 DevEco 官方文档配置工程级 build-profile.json5 的 products |
9.3 参考资料
- CPF-Flutter/flutter_flutter(本文主仓库,OpenHarmony 版 Flutter SDK + Engine) :https://atomgit.com/CPF-Flutter/flutter_flutter
- Flutter OH 开发文档 / 环境搭建与应用构建指导 (flutter_samples,README 内指引,原 gitcode 地址迁移后对应 atomgit 仓库,注意组织已由 openharmony-tpc 迁至 CPF-Flutter):https://atomgit.com/openharmony-tpc/flutter_samples
- Flutter 官方开发指南与 API 文档 :https://docs.flutter.dev/
- FVM(Flutter 版本管理)官方文档 :https://fvm.app/
- DevEco Studio / HarmonyOS 官方文档 (hvigor、npmrc、SDK 许可等配置):https://developer.harmonyos.com/
- OpenHarmony 官方文档 (hdc 工具链、设备连接):https://docs.openharmony.cn/
- GitHub 上游 flutter/flutter (官方基线版本):https://github.com/flutter/flutter