系列导航：
我第一次让 FVM 管理鸿蒙版 Flutter SDK 时，前后踩了 4 个坑，花了大半天才跑通。事后复盘发现，每个坑都不难，只是没人提前告诉我"为什么要这样做"。这篇把整个过程拆成 5 关，每关讲清「为什么」和「怎么做」，争取让你 20 分钟一次通关。
前置条件：请先完成第一篇的全部内容------DevEco Studio 已安装，ohpm、node、hvigorw 在终端里都能正常调用。
🗺️ 通关路线图
| 关卡 | 任务 | 预计耗时 |
|---|---|---|
| 第1关 | 安装 FVM | 2 min |
| 第2关 | 克隆鸿蒙版 SDK | 5 min（取决于网速） |
| 第3关 | 修复版本"身份证" | 3 min |
| 第4关 | 指定鸿蒙 SDK 路径 | 1 min |
| 第5关 | 全绿验证 | 2 min |
🎯 第 1 关：安装 FVM
目标
让终端认识 fvm 命令。
为什么需要 FVM
一句话------让不同项目用不同版本的 Flutter，互不干扰。比如项目 A 用官方 3.24 跑 Android/iOS，项目 B 用鸿蒙版 3.35.8。FVM 就是 Flutter 的"版本档案柜"，每个抽屉放一个版本。
📋 操作
bash
# macOS（在终端里执行，这是用 Homebrew 包管理器安装 FVM）
brew install fvm
bash
# Windows（在 cmd 或 PowerShell 中执行，这是用 Chocolatey 包管理器安装 FVM）
choco install fvm安装完后，配置 FVM 缓存路径。把以下两行写入 ~/.zshrc（上一篇介绍过，这是 Mac 终端的配置文件）：
bash
# FVM 存放所有 Flutter 版本的目录
export FVM_CACHE_PATH=$HOME/fvm
# 让 FVM 的默认版本可以直接用 flutter 命令调用
export PATH="$HOME/fvm/default/bin:$PATH"保存后执行下面这条命令，让刚才的配置立即生效（否则要关掉终端重新打开）：
bash
source ~/.zshrc✅ 验证
bash
# 查看 FVM 版本号，确认安装成功
fvm --version看到版本号（如 3.1.4）就过关了。
⚠️ 如果报
command not found：Mac 用户确认已安装 Homebrew（执行brew --version看有没有输出）；Windows 用户确认已安装 Chocolatey（执行choco --version）。如果包管理器本身都没装，请先去官网安装。
🎯 第 2 关：克隆鸿蒙版 SDK
目标
把华为的鸿蒙版 Flutter 放进 FVM 管辖。
为什么不能直接 fvm install
正常装 Flutter 只需要 fvm install 3.24.0，FVM 会自动去 GitHub 下载。但鸿蒙版是华为团队在 AtomGit（国内代码托管平台）上单独维护的，FVM 的世界里它根本不存在。所以我们要"手动入库"------自己下载代码，放到 FVM 的档案柜里，假装它一直在那。
⚠️ 本关最大的坑：分支名和版本号是两回事！
仓库的分支叫
oh-3.35.7-dev，看到3.35.7你会以为版本就是 3.35.7。但实际上代码里的版本已经迭代到了3.35.8-ohos-0.0.2。类比：Git 分支叫
feature/login-v1，但代码早就改到 v3 了。分支名是创建时起的，不会跟着版本号自动更新。千万别拿分支名当版本号用，团队必须统一用
3.35.8-ohos-0.0.2这个真实版本号。
📋 操作
bash
# --depth 1 只取最新代码，省空间（省去几个 GB 的历史记录）
git clone -b oh-3.35.7-dev --depth 1
https://atomgit.com/openharmony-tpc/flutter_flutter.git
~/fvm/versions/3.35.8-ohos-0.0.2注意看：clone 命令里分支名是 oh-3.35.7-dev，但目标文件夹名是 3.35.8-ohos-0.0.2------这不是写错了，上面已经解释了为什么不一样。
💡 怎么确认真实版本号？ clone 完后执行
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter --version看输出。如果加入已有团队，直接看项目的.fvmrc文件（命令：cat .fvmrc）。
✅ 验证
bash
# 确认文件下载成功（ls = 列出目录内容）
ls ~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter文件存在就过关。
⚠️ 如果报
No such file or directory：回去检查 clone 命令是否执行成功。常见原因是网络超时（AtomGit 在国内，通常不需要梯子，但公司内网可能有限制）。重新执行 clone 前，先删掉残留目录：rm -rf ~/fvm/versions/3.35.8-ohos-0.0.2，再重试。
🎯 第 3 关：修复版本"身份证"
目标
让 FVM 正确识别这个 SDK 的版本号。
为什么要做这步
clone 下来的 SDK 有两张"证件"：
version文件 ------相当于身份证，一行文本写着版本号bin/cache/flutter.version.json------相当于内部档案，JSON 格式的详细版本信息
问题是，这两张证件上都写着 0.0.0-unknown（因为鸿蒙团队是从开发分支构建的，没有打标准标签）。但我们的文件夹名叫 3.35.8-ohos-0.0.2。FVM 一查------名字对不上，直接翻脸。
⚠️ 不做这步的后果 ：FVM 会弹出 "Version mismatch" 并试图删掉你的 SDK 重装。如果看到了这个弹窗，千万不要选任何选项 ，按
Ctrl+C（Mac 也是 Ctrl 不是 Cmd）退出，回来做这步。
📋 操作
macOS / Linux：
bash
cd ~/fvm/versions/3.35.8-ohos-0.0.2
# 第一步：改"身份证"
echo -n "3.35.8-ohos-0.0.2" > version
# 第二步：初始化 Flutter 引擎（首次运行会下载 Dart SDK，需要等 1-3 分钟）
bin/flutter --version
# 第三步：改"内部档案"（把所有 0.0.0-unknown 替换成正确的版本号）
sed -i '' 's/0.0.0-unknown/3.35.8-ohos-0.0.2/g' bin/cache/flutter.version.jsonWindows PowerShell：
bash
# 进入 SDK 所在目录
cd $env:USERPROFILE\fvm\versions\3.35.8-ohos-0.0.2
# 第一步：改"身份证"
"3.35.8-ohos-0.0.2" | Set-Content version -NoNewline
# 第二步：初始化引擎
bin\flutter --version
# 第三步：改"内部档案"（PowerShell 的查找替换写法）
(Get-Content bin\cache\flutter.version.json) -replace '0.0.0-unknown', '3.35.8-ohos-0.0.2' | Set-Content bin\cache\flutter.version.json⚠️ 三步的顺序不能乱------第二步会生成
flutter.version.json文件，第三步才有东西可改。如果你先执行了第三步，会报文件不存在。
✅ 验证
bash
# 回到任意目录都可以执行（fvm list = 列出 FVM 管理的所有 Flutter 版本）
fvm list看到 Version 列显示 3.35.8-ohos-0.0.2（不是空白、不是 Need setup、不是 0.0.0-unknown），这关就过了。
⚠️ 如果还是显示异常，逐一排查两张"证件"：
bash# 检查"身份证"内容 cat ~/fvm/versions/3.35.8-ohos-0.0.2/version # 应该输出：3.35.8-ohos-0.0.2（没有多余空行） # 检查"内部档案"有没有残留的 0.0.0-unknown cat ~/fvm/versions/3.35.8-ohos-0.0.2/bin/cache/flutter.version.json # 里面所有 version 字段应该都是 3.35.8-ohos-0.0.2如果
version文件内容不对，重新执行第一步；如果 JSON 里还有0.0.0-unknown，重新执行第三步。
🎯 第 4 关：指定鸿蒙 SDK 路径
目标
让 Flutter 知道鸿蒙的 SDK（OpenHarmony SDK）装在哪。
为什么不用环境变量
我试过 HOS_SDK_HOME、OHOS_SDK_HOME 等环境变量，时灵时不灵。原因是不同方式打开的终端（VS Code 内置终端 vs 系统终端 vs CI 环境）加载配置文件的顺序不一样，变量可能没被读到。flutter config 会把路径写入 Flutter 自己的配置文件，不管从哪里启动都能读到，最稳。
📋 操作
bash
# 把鸿蒙 SDK 的位置"写死"到 Flutter 的配置里（一次性操作）
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter config \
--ohos-sdk="/Applications/DevEco-Studio.app/Contents/sdk"⚠️ Windows 用户路径改为：
--ohos-sdk="C:\Program Files\Huawei\DevEco Studio\sdk"
请根据 DevEco Studio 实际安装路径调整。不确定装在哪？打开 DevEco Studio → Settings → SDK 页面可以看到路径。
终端输出 Setting "ohos-sdk" value to "..." 就成功了。
✅ 验证
不急，下一关一起验收。
🎯 第 5 关：全绿验证
目标
flutter doctor 中 HarmonyOS toolchain 一栏显示绿色对勾。
📋 操作
bash
# 运行 Flutter 的环境诊断工具（-v 表示显示详细信息）
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter doctor -v✅ 验证
关注输出中的 HarmonyOS 那一栏：
text
[✓] HarmonyOS toolchain - develop for HarmonyOS devices
• OpenHarmony Sdk at /Applications/DevEco-Studio.app/Contents/sdk,
available api versions has [22:default]
• Ohpm version 6.0.1
• Node version v18.20.1
• Hvigorw binary at .../hvigor/bin/hvigorw看到 [✓] 加上 4 个子项都有值 = 通关！
💡 你可能会看到 Flutter 那栏有几个
!警告（channel 不标准、upstream 不是官方地址）。这是鸿蒙版的正常现象，完全不影响开发和打包，放心忽略。⚠️ 如果 HarmonyOS 那栏还是红叉，按优先级排查：
- SDK not found → 回第 4 关检查 config 路径是否正确
- ohpm/hvigorw missing → 回第一篇检查环境变量
- Version mismatch → 回第 3 关检查两张"证件"
🔧 附加关：FVM 的"碎碎念"
通关后你会发现，每次用 fvm flutter xxx 时 FVM 都会弹 "not a valid version" 的警告让你确认。这不是报错，只是 FVM 在说："这个版本号我在官方列表里查不到，你确定要用吗？"
三种应对方式：
- 手动按 y ------每次弹出输入
y回车 - 自动确认 ------命令前加
yes |：
bash
yes | fvm flutter doctor- 绕过 FVM------直接用绝对路径调用，完全不弹警告：
bash
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter doctor我推荐第三种，路径虽长但最省心。可以设个快捷方式（alias）缩短它：
bash
# 把这行加到 ~/.zshrc 里（alias = 给一条长命令起个短名字）
alias hflutter="$HOME/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter"保存后 source ~/.zshrc，之后直接 hflutter run、hflutter doctor 就行。
🏆 通关总结
| 项目 | 状态 |
|---|---|
| FVM | ✅ 已安装 |
| 鸿蒙版 Flutter SDK | ✅ ~/fvm/versions/3.35.8-ohos-0.0.2 |
| version 文件 | ✅ 已修复 |
| flutter.version.json | ✅ 已修复 |
| flutter config --ohos-sdk | ✅ 已配置 |
| flutter doctor HarmonyOS | ✅ 全绿 |
回顾核心逻辑：FVM 只管官方 Flutter，鸿蒙版要我们手动塞进去（第 2 关）；塞进去后"证件"信息对不上，需要手动修正（第 3 关）；最后告诉 Flutter 鸿蒙 SDK 在哪（第 4 关）。理解了这条线，以后鸿蒙版 SDK 升级换版本号，你也能照样搞定。
如果中途卡住，大概率是版本号写错了------检查文件夹名、version 文件内容、flutter.version.json 里的版本号，三者必须完全一致。
下一篇预告 ：SDK 准备好了，接下来要把你的老 Flutter 项目跑到鸿蒙上------听起来就是敲几行命令的事？没那么简单。→ Flutter 鸿蒙通关手册（三）：项目搬家