FVM 使用说明（Windows / 独立安装）

适用于 FVM 4.x（如 4.0.5）。推荐使用 GitHub Releases 的 Windows 独立安装包，不要与 dart pub global activate fvm 混用（两套并存时容易指到旧版）。

介绍

FVM（Flutter Version Management） 是 Flutter 的版本管理工具，作用类似 Node 的 nvm：在同一台电脑上安装、切换多套 Flutter SDK，并按项目锁定版本。

解决什么问题

  • 不同项目依赖不同 Flutter 版本（例如 A 要 3.7，B 要 3.22）
  • 避免全局只装一套 SDK、来回卸载/重装
  • 团队统一项目所用 SDK，减少「我这边能跑你那边不行」

能做什么

能力 说明
多版本并存 多个 Flutter SDK 缓存在本地（如 ...\fvm\versions\）
按项目切换 fvm use <版本>，项目目录下用对应 SDK
统一调用 fvm flutter ... / fvm dart ...，走当前项目配置的 SDK
自定义源 fvm fork 可接官方仓、鸿蒙适配仓或本地 git 仓

和「直接装 Flutter」的区别

  • 全局 Flutter：系统里通常一套，改版本影响所有项目
  • FVM：每个项目可指定自己的版本；日常尽量用 fvm flutter，而不是裸的 flutter

一句话：FVM = 给 Flutter 用的多版本管理器，方便本地开发和鸿蒙/官方多套 SDK 并存。

1. 下载与安装

  1. 打开：https://github.com/leoafarias/fvm/releases
  2. 下载对应系统的 Windows 包（如 fvm-*-windows-x64.zip）
  3. 解压到固定目录，例如：D:\Tools\fvm（目录内应有 fvm.exe）

2. 配置环境变量

2.1 把 FVM 加入 PATH（必做）

否则终端会提示找不到 fvm 命令。

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
  2. 在「用户变量」或「系统变量」中编辑 Path
  3. 新建一条，指向 fvm.exe 所在目录，例如：D:\Tools\fvm
  4. 确定保存后，关闭并重新打开所有终端（必要时重启 IDE）

验证：

where.exe fvm
fvm --version

where.exe fvm 的第一条应是你刚配置的独立安装路径。

2.2 自定义 SDK 缓存目录（可选）

默认缓存一般在用户目录下。若希望装到指定盘：

项 示例
变量名 FVM_CACHE_PATH
变量值 E:\tools\fvm（缓存根目录，不要写成 ...\versions）

实际 SDK 会装在：%FVM_CACHE_PATH%\versions\
例如：E:\tools\fvm\versions\oh_flutter\oh-3.27.0-release

修改后同样需要重开终端。也可用：

fvm config --cache-path E:\tools\fvm

3. 配置仓库别名（fork）

FVM 4.x 要求地址为合法 Git URL，且以 .git 结尾。本地路径不能直接写 E:\xxx，必须用 file:/// 形式。

3.1 本地仓库

fvm fork add oh_flutter file:///F:/0814_Flutter/flutter_flutter/.git

说明：

  • 使用 file:///（三个斜杠）
  • Windows 盘符写成 F:，路径用 /
  • 末尾必须是 /.git
  • 目标目录本身需是完整 git 仓库

3.2 远程仓库

# 谷歌官方 Flutter SDK
fvm fork add google-official https://github.com/flutter/flutter.git

# 鸿蒙适配 Flutter SDK（CPF-Flutter）
fvm fork add oh_cpf_flutter https://gitcode.com/CPF-Flutter/flutter_flutter.git

oh_flutter、google-official、oh_cpf_flutter 都是自定义别名，可按需命名。

3.3 查看 / 删除别名

fvm fork list
fvm fork remove oh_flutter

注意：fork remove 只删别名配置，不会删除已安装的 SDK 目录。

4. 安装指定版本

格式：fvm install <别名>/<版本或分支>

# 鸿蒙 fork 示例（分支/标签名以仓库实际为准）
fvm install oh_cpf_flutter/oh-3.41.9-release
fvm install oh_cpf_flutter/oh-3.35.7-release
fvm install oh_cpf_flutter/oh-3.27.0-release
fvm install oh_cpf_flutter/oh-3.22.3-release
fvm install oh_cpf_flutter/br_3.7.12-ohos-1.1.3

# 谷歌官方示例
fvm install google-official/stable
fvm install google-official/3.7.12

如何知道能装哪些版本？

  • 官方仓库：可用 fvm releases（可按 channel 过滤），例如：
    fvm releases / fvm releases -c all

    fvm releases 不能写成 fvm releases 别名，它不接受 fork 别名参数。

  • 自定义 fork（鸿蒙等）：到对应 Git 仓库查看 分支 / Tag，再用 别名/分支名 安装。

同一分支若要更新到远程最新内容：先 fvm remove 别名/版本，再重新 fvm install。
只更新本地源仓库代码，不会自动更新 FVM 已安装缓存。

5. 卸载已安装的 Flutter SDK

fvm remove oh_cpf_flutter/oh-3.22.3-release
fvm remove <别名>/<版本>

若提示 Deletion failed，多半是该 SDK 正被 Cursor/VS Code 的 Dart 分析服务、Flutter daemon 占用。先关闭相关 IDE/进程，再删；或直接删除对应目录：

Remove-Item -Recurse -Force E:\tools\fvm\versions\<别名>\<版本>

删除某个别名下全部版本（FVM 无官方一键命令）可删整个别名目录：

Remove-Item -Recurse -Force E:\tools\fvm\versions\oh_cpf_flutter

不要用 fvm remove --all / fvm destroy，除非你确认要清空所有别名的缓存。

6. 查看已安装版本

fvm list

在这里插入图片描述

关注表格中的 Version、Local（当前项目所用会有标记）等列。

7. 切换项目使用的版本

在项目根目录执行（Version 列内容可直接复制）：

fvm use google-official/3.7.12

可选全局默认：

fvm global google-official/3.7.12

检查是否切换成功

fvm flutter --version
fvm flutter doctor -v

日常命令请通过 FVM 调用，例如：

fvm flutter pub get
fvm flutter build hap

8. 常见问题

8.1 终端提示找不到 fvm 命令

在这里插入图片描述

  • 检查 PATH 是否包含 fvm.exe 所在目录
  • 重开终端 / 重启 IDE / 必要时注销或重启电脑
  • 用 where.exe fvm 确认实际调用的是哪一个（避免指到旧的 Pub\bin\fvm.bat）

8.2 fvm use 提示无权创建符号链接

推荐：开启 Windows 开发人员模式

设置 → 系统 → 开发者选项（或搜索「开发人员模式」）→ 打开。

开启后普通权限即可创建符号链接。

备选：以管理员身份运行终端，再执行 fvm use。

切换成功后，在 fvm list 中对应版本的 Local 列一般会有标记。

8.3 切换版本异常

可尝试删除项目根目录下的 .fvm 与 .fvmrc，再重新执行：

fvm use <别名>/<版本>

8.4 想把别名 oh_cpf_flutter 改成 oh_flutter

FVM 无 rename，需：删旧别名 → 用新名字 fork add → 如需保留已装 SDK，将
versions\oh_cpf_flutter 重命名为 versions\oh_flutter，并改项目 .fvmrc 中的版本字符串。

9. 常用命令速查

命令 作用
fvm --version 查看 FVM 版本
fvm fork add <别名> <url.git> 添加仓库别名
fvm fork list 查看别名
fvm fork remove <别名> 删除别名（不删已装 SDK）
fvm install <别名>/<版本> 安装 SDK
fvm remove <别名>/<版本> 卸载某个 SDK
fvm list 查看已安装 SDK
fvm use <别名>/<版本> 当前项目切换版本
fvm global <别名>/<版本> 设置全局默认版本
fvm flutter ... 用当前项目 SDK 执行 flutter
fvm releases 查看官方可安装的发布版本（非 fork 分支列表）
# windows
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

鸿蒙ArkTS深度解析：智能睡眠监测中心的夜空安眠风UI架构与动画系统

avatar 人工智能6S服务平台
cover

鸿蒙（HarmonyOS NEXT）开发小白入门学习计划表

avatar 人工智能6S服务平台
cover

华为鸿蒙免费记录当下APP—小羊在呢

avatar 人工智能6S服务平台