Windows 鸿蒙 Flutter 环境搭建指南
工具链:Chocolatey(包管理器) + Git + FVM(Flutter Version Management,版本管理器)
目标 Flutter 版本:
3.41.9+ohos-1.0.2(鸿蒙定制分支)
🎯 目标与前置说明
最终需要达到的状态
| # | 验收项 | 期望结果 |
|---|---|---|
| 1 | choco --version | 正常输出版本号 |
| 2 | git --version | 正常输出版本号 |
| 3 | fvm --version | 正常输出版本号 |
| 4 | fvm global ohos/3.41.9+ohos-1.0.2 | 执行成功 |
| 5 | flutter --version | 显示鸿蒙版 Flutter 3.41.9+ohos-1.0.2 |
| 6 | fvm flutter doctor -v | 无报错 |
⚠️ 全程注意事项
- 权限:所有步骤在管理员权限的 PowerShell 中操作(右键 PowerShell → 以管理员身份运行)
- 刷新终端:每次安装新工具后,必须关闭并重新打开终端,让环境变量和 PATH 生效
- 国内网络:文档已内置国内镜像源,确保下载速度和稳定性
第一部分:安装基础工具
步骤一:安装 Chocolatey
Chocolatey 是 Windows 包管理器,类似 macOS 的 Homebrew 或 Linux 的 apt。
1.1 放开执行策略(仅对当前窗口生效,安全无副作用)
Set-ExecutionPolicy Bypass -Scope Process -Force
1.2 执行 Chocolatey 官方安装脚本
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
1.3 ✅ 验证
关闭当前 PowerShell,重新以管理员身份打开,执行:
choco --version
成功输出版本号(如 2.7.1)即表示 Chocolatey 安装成功。
步骤二:使用 Chocolatey 安装 Git
choco install git -y
参数说明:-y 表示自动确认所有安装提示,无需手动输入 Yes。
✅ 验证
关闭并重新打开一个新的终端窗口,执行:
git --version
成功输出版本号(如 git version 2.48.1.windows.1)即表示 Git 安装成功。
步骤三:使用 Chocolatey 安装 FVM
FVM(Flutter Version Management)是 Flutter 版本管理工具,可以在多个 Flutter 版本之间快速切换。
choco install fvm -y
✅ 验证
关闭当前终端,打开一个新的 PowerShell 窗口,执行:
fvm --version
成功输出版本号(如 4.0.5)即表示 FVM 安装成功。
如果提示「找不到命令」,请参考步骤四补充 PATH 环境变量。
第二部分:配置环境变量与安装鸿蒙 Flutter
步骤四:配置环境变量
以下命令通过 setx 设置用户级持久化环境变量,设置后将永久生效(但需重新打开终端才能在当前会话中使用)。
4.1 设置国内镜像(Flutter 存储 + Pub 包管理)
setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn"
setx PUB_HOSTED_URL "https://pub.flutter-io.cn"
4.2 设置鸿蒙 Flutter 仓库地址
setx FVM_FLUTTER_URL "https://gitcode.com/CPF-Flutter/flutter_flutter.git"
4.3 💡 补充 PATH(如果 fvm 命令不可用)
通常 Chocolatey 会自动将 FVM 加入 PATH。如果步骤三验证失败,手动将以下路径加入系统 PATH:
C:\ProgramData\chocolatey\lib\fvm\bin\
操作方式:
Win + R→ 输入sysdm.cpl→ 高级 → 环境变量 → 系统变量 → Path → 编辑 → 新建 → 粘贴上述路径。
4.4 🔄 使环境变量生效
关闭所有终端窗口,重新打开一个新的管理员 PowerShell。
步骤五:注册鸿蒙 Flutter Fork 并安装指定版本
鸿蒙 Flutter 是 Flutter 的一个定制分支(fork),FVM 通过注册 fork 别名来管理自定义仓库。
5.1 注册 Fork 别名
fvm fork add ohos https://gitcode.com/CPF-Flutter/flutter_flutter.git
- 如果提示「已存在」,说明之前已注册,直接跳过此步
ohos是自定义别名,后续安装和引用都用这个名字
5.2 安装指定版本
fvm install ohos/3.41.9+ohos-1.0.2
💡 此命令会从鸿蒙 Flutter 仓库克隆并检出
3.41.9+ohos-1.0.2标签,首次下载可能需要几分钟(取决于网络速度)。
5.3 ✅ 验证安装结果
fvm list
输出示例(重点看 Version 列是否包含目标版本):
Cache directory: C:\Users\你的用户名\fvm\versions
┌─────────────────────────┬─────────┬─────────────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version │ Channel │ Flutter Version │ Dart Version │ Release Date │ Global │ Local │
├─────────────────────────┼─────────┼─────────────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.41.9+ohos-1.0.2 │ │ 3.41.9+ohos-1.0.2 │ ... │ │ │ │
└─────────────────────────┴─────────┴─────────────────────────┴──────────────┴──────────────┴────────┴───────┘
列表中能看到 3.41.9+ohos-1.0.2 即表示安装成功。
🛠️ 备用方案:网络失败时手动克隆
如果 fvm install 因网络问题超时失败,可以手动执行 Git 克隆:
第一步:找到 FVM 的缓存目录
fvm list
查看输出中的 Cache directory(例如 C:\Users\niuhk\fvm\versions)。
第二步:在该目录下手动克隆仓库并检出目标标签
# 切换到缓存目录(替换为你自己的路径)
cd C:\Users\niuhk\fvm\versions
# 克隆仓库
git clone https://gitcode.com/CPF-Flutter/flutter_flutter.git custom_3.41.9+ohos-1.0.2
# 进入克隆目录
cd custom_3.41.9+ohos-1.0.2
# 检出目标标签
git checkout 3.41.9+ohos-1.0.2
第三步:回到用户主目录,继续执行步骤六(全局版本设置),但版本名改为 custom_3.41.9+ohos-1.0.2。
第三部分:全局验证与排错
步骤六:设置全局版本并验证检测
6.1 设为全局默认版本
# 正常情况
fvm global ohos/3.41.9+ohos-1.0.2
# 如果用了手动克隆的备用方案,版本名改为:
fvm global custom_3.41.9+ohos-1.0.2
6.2 ✅ 全新终端验证
关闭当前终端,打开一个全新的 PowerShell(非管理员也可以),依次执行以下所有命令:
# 验证基础工具
fvm --version
fvm list
# 验证 Flutter 版本(关键!)
flutter --version
# 完整健康检查
fvm flutter doctor -v
🎯 成功标准 Checklist
-
flutter --version输出第一行包含Flutter 3.41.9+ohos-1.0.2 -
fvm flutter doctor -v所有检查项均无红色错误 -
fvm list中目标版本的 Global 列显示 ●
⚠️ 常见排错
问题:flutter --version 显示的不是目标版本
原因通常是 PATH 优先级不对,系统找到了另一个 Flutter 安装。
# 查看 flutter 命令的实际调用路径
where flutter
确保 FVM 管理的路径(通常在 C:\Users\用户名\fvm\versions\...)排在最前面。如果不是,调整系统 PATH 顺序,把 FVM 路径移到顶部。
📋 完整命令
# ===== 步骤一:Chocolatey =====
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
# ===== 步骤二:Git =====
choco install git -y
# ===== 步骤三:FVM =====
choco install fvm -y
# ===== 步骤四:环境变量 =====
setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn"
setx PUB_HOSTED_URL "https://pub.flutter-io.cn"
setx FVM_FLUTTER_URL "https://gitcode.com/CPF-Flutter/flutter_flutter.git"
# ===== 步骤五:注册 Fork + 安装 =====
fvm fork add ohos https://gitcode.com/CPF-Flutter/flutter_flutter.git
fvm install ohos/3.41.9+ohos-1.0.2
# ===== 步骤六:设为全局 =====
fvm global ohos/3.41.9+ohos-1.0.2