Windows 鸿蒙 Flutter 环境搭建指南

4 阅读5分钟

Windows 鸿蒙 Flutter 环境搭建指南

工具链:Chocolatey(包管理器) + Git + FVM(Flutter Version Management,版本管理器)

目标 Flutter 版本:3.41.9+ohos-1.0.2(鸿蒙定制分支)


🎯 目标与前置说明

最终需要达到的状态

#验收项期望结果
1choco --version正常输出版本号
2git --version正常输出版本号
3fvm --version正常输出版本号
4fvm global ohos/3.41.9+ohos-1.0.2执行成功
5flutter --version显示鸿蒙版 Flutter 3.41.9+ohos-1.0.2
6fvm 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