FVM 与 Flutter 环境配置完全指南：从安装到日常使用

本文整理自 Flutter 多版本管理工具 FVM 的官方文档与社区实践，覆盖安装配置、常用命令、环境变量与国内镜像加速，适合作为日常速查手册收藏。

一、FVM 是什么，为什么值得用

在 Flutter 开发中，不同项目往往依赖不同版本的 Flutter SDK。手动切换全局 SDK 不仅低效，还容易导致团队协作时版本不一致。FVM（Flutter Version Management）正是为解决这一问题而设计的工具。

FVM 的核心能力包括：

项目级版本控制：每个项目可锁定独立的 Flutter SDK 版本，互不干扰
快速切换：版本切换无需重新下载 SDK，秒级完成
团队一致性 ：通过 .fvmrc 文件记录项目版本，团队成员一键还原
缓存可视化：清晰查看哪些 SDK 被使用、哪些未被引用，便于清理

二、安装 FVM

2.1 前置条件

建议先按 Flutter 官方安装指南全局安装一个 Flutter SDK，作为机器上的"主版本"。FVM 则用于管理各项目的特定版本。

2.2 安装方式

方式一：Dart Pub 全局激活（跨平台通用）

前提是系统中已有可用的 dart 命令（通常随 Flutter 一起安装）。

bash 复制代码

dart pub global activate fvm

安装后需确保 Dart 全局包的 bin 目录已加入系统 PATH。Windows 下该目录通常为：

复制代码

C:\Users\<用户名>\AppData\Local\Pub\Cache\bin

macOS/Linux 下通常为：

复制代码

~/.pub-cache/bin

方式二：Homebrew（macOS/Linux）

bash 复制代码

brew install fvm

方式三：Chocolatey（Windows）

powershell 复制代码

choco install fvm

方式四：独立安装脚本（推荐）

bash 复制代码

curl -fsSL https://fvm.app/install.sh | bash

如需指定版本：curl -fsSL https://fvm.app/install.sh | bash -s -- <version>

2.3 验证安装

关闭当前终端，重新打开后执行：

bash 复制代码

fvm --version

若提示"command not found"，请检查 FVM 的安装目录是否已加入 PATH。

三、FVM 常用命令速查

3.1 版本安装与切换

命令	作用	示例
`fvm install [version]`	下载并缓存指定 Flutter 版本	`fvm install 3.22.0`
`fvm install`	根据项目 `.fvmrc` 安装对应版本	`fvm install`
`fvm use [version]`	为当前项目锁定 Flutter 版本	`fvm use 3.22.0`
`fvm use stable --pin`	锁定当前 stable 最新版	`fvm use stable --pin`
`fvm global [version]`	设置全局默认 Flutter 版本	`fvm global 3.22.0`
`fvm remove [version]`	删除指定版本 SDK	`fvm remove 3.19.0`
`fvm destroy`	清空 FVM 所有缓存	`fvm destroy`

fvm use 执行后会在项目根目录生成 .fvmrc 文件，并创建 .fvm/flutter_sdk 符号链接。.fvmrc 应提交到 Git，确保团队一致。

3.2 版本查看与管理

命令	作用
`fvm list` / `fvm ls`	列出已安装的所有 Flutter 版本
`fvm releases`	列出可安装的 Flutter 版本（需联网）
`fvm cleanup`	查看可清理的未使用 SDK 和补丁升级
`fvm cleanup --remove-unused`	移除未使用的 SDK

fvm list 会标注每个 SDK 的状态：Local（被当前目录项目锁定）、Global（全局默认）、Unused（无项目引用）。Unused 仅作为清理提示，FVM 不会自动删除。

3.3 执行 Flutter/Dart 命令

使用 FVM 管理版本后，所有 Flutter 命令需加 fvm 前缀：

bash 复制代码

fvm flutter doctor
fvm flutter pub get
fvm flutter run
fvm flutter build apk --release
fvm dart analyze
fvm dart format .

FVM 按以下优先级查找 SDK：项目 .fvmrc → 全局版本 → 系统 PATH 中的 Flutter。

3.4 临时使用特定版本

bash 复制代码

fvm spawn 3.22.0 test

该命令使用指定版本执行一次操作，不改变项目的锁定版本。

四、环境变量配置

4.1 必须配置的环境变量

以下变量用于让 Flutter 和 Dart Pub 从国内镜像下载资源，国内开发者强烈建议配置：

变量名	用途	推荐值
`PUB_HOSTED_URL`	Dart 包仓库地址	`https://pub.flutter-io.cn`
`FLUTTER_STORAGE_BASE_URL`	Flutter 二进制资源地址	`https://storage.flutter-io.cn`

Windows（PowerShell 永久设置）：

powershell 复制代码

[System.Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", "https://pub.flutter-io.cn", "User")
[System.Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", "https://storage.flutter-io.cn", "User")

设置后需新开终端窗口生效。

macOS/Linux：

在 ~/.zshrc 或 ~/.bash_profile 中添加：

bash 复制代码

export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

然后 source ~/.zshrc 生效。

4.2 FVM 专用环境变量

变量名	用途	说明
`FVM_FLUTTER_URL`	自定义 Flutter SDK 的 Git 仓库地址	国内加速关键变量
`FVM_CACHE_PATH`	自定义 FVM 缓存目录	默认 `~/.fvm`
`FVM_GIT_CACHE_PATH`	Git 缓存位置	可加速重复下载

FVM_FLUTTER_URL 国内镜像推荐值：

bash 复制代码

export FVM_FLUTTER_URL="https://gitee.com/mirrors/Flutter.git"

或使用清华 TUNA 镜像：

bash 复制代码

export FVM_FLUTTER_URL="https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git"

FVM 默认从 GitHub 拉取 Flutter SDK，国内访问不稳定。设置此变量后，fvm install 会改从国内镜像拉取。

Windows 设置方式：

powershell 复制代码

[System.Environment]::SetEnvironmentVariable("FVM_FLUTTER_URL", "https://gitee.com/mirrors/Flutter.git", "User")

五、国内镜像加速完整方案

5.1 镜像源对比

镜像源	PUB_HOSTED_URL	FLUTTER_STORAGE_BASE_URL	特点
腾讯云	`https://mirrors.cloud.tencent.com/dart-pub`	`https://mirrors.cloud.tencent.com/flutter`	稳定，社区推荐
阿里云	`https://mirrors.aliyun.com/dart-pub`	`https://mirrors.aliyun.com/flutter`	更新频率高
上海交大	`https://mirror.sjtu.edu.cn/dart-pub`	`https://mirror.sjtu.edu.cn`	教育网友好
CFUG	`https://pub.flutter-io.cn`	`https://storage.flutter-io.cn`	Flutter 中文社区维护

5.2 推荐配置组合

bash 复制代码

# Dart 包镜像（腾讯云）
export PUB_HOSTED_URL="https://mirrors.cloud.tencent.com/dart-pub"
# Flutter 资源镜像（腾讯云）
export FLUTTER_STORAGE_BASE_URL="https://mirrors.cloud.tencent.com/flutter"
# FVM 拉取 SDK 的 Git 镜像（Gitee）
export FVM_FLUTTER_URL="https://gitee.com/mirrors/Flutter.git"

这一组合在社区中被广泛验证，兼顾速度与稳定性。

5.3 验证配置

新开终端后执行：

bash 复制代码

echo $env:FLUTTER_STORAGE_BASE_URL   # PowerShell
echo $FLUTTER_STORAGE_BASE_URL        # bash/zsh

确认输出与设置值一致后，再运行 fvm install。

5.4 如果镜像仍慢：手动下载 SDK

若 fvm install 持续超时，可从国内镜像手动下载 Flutter SDK 压缩包，解压后放入 FVM 的缓存目录，再执行 fvm use 让 FVM 识别。

腾讯云 Flutter 镜像地址：

复制代码

https://mirrors.cloud.tencent.com/flutter/

下载对应版本的 Windows/macOS/Linux 压缩包，解压到 ~/.fvm/versions/<版本号> 目录即可。

六、常见问题排查

6.1 `fvm` 命令找不到

确认 FVM 安装目录已加入 PATH。Windows 下通常为：

复制代码

%LOCALAPPDATA%\Pub\Cache\bin

macOS/Linux 下为 ~/.pub-cache/bin。添加后需新开终端。

6.2 `fvm use` 后 Flutter 版本未变化

检查项目根目录是否存在 .fvmrc 文件。如果没有，说明 fvm use 未成功执行。在项目目录中重新执行 fvm use <version>。

6.3 `fvm install` 超时或失败

优先检查 FVM_FLUTTER_URL 是否已设置为国内镜像。未设置时 FVM 会从 GitHub 拉取，国内访问容易超时。

6.4 安装后 `fvm list` 显示 "needs setup"

执行以下命令补全 SDK 依赖：

bash 复制代码

fvm install <version> --setup

--setup 会下载 SDK 所需的额外资源，确保版本可用。

6.5 IDE 识别不到 FVM 管理的 Flutter

VS Code 用户可在 .vscode/settings.json 中设置：

json 复制代码

{
  "dart.flutterSdkPath": ".fvm/flutter_sdk"
}

Android Studio 用户可在设置中将 Flutter SDK 路径指向项目的 .fvm/flutter_sdk 目录。

七、最佳实践清单

实践	说明
提交 `.fvmrc` 到 Git	保证团队成员使用同一 Flutter 版本
`.fvm/flutter_sdk` 加入 `.gitignore`	符号链接不应提交
始终使用 `fvm flutter` 前缀	避免误用系统全局 Flutter 版本
定期运行 `fvm cleanup`	清理未使用的 SDK，节省磁盘
国内环境配置三个镜像变量	`PUB_HOSTED_URL`、`FLUTTER_STORAGE_BASE_URL`、`FVM_FLUTTER_URL`
版本号精确到补丁	如 `3.22.0` 而非 `3.22`，避免解析歧义

八、完整安装流程速览

bash 复制代码

# 1. 安装 FVM
dart pub global activate fvm

# 2. 新开终端，配置国内镜像（以 PowerShell 为例）
[System.Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", "https://mirrors.cloud.tencent.com/dart-pub", "User")
[System.Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", "https://mirrors.cloud.tencent.com/flutter", "User")
[System.Environment]::SetEnvironmentVariable("FVM_FLUTTER_URL", "https://gitee.com/mirrors/Flutter.git", "User")

# 3. 再开新终端，安装指定 Flutter 版本
fvm install 3.22.0

# 4. 进入项目目录，锁定版本
cd /path/to/project
fvm use 3.22.0

# 5. 验证
fvm flutter --version

# 6. 用 FVM 版本执行构建
fvm flutter build apk --release

以上就是 FVM 与 Flutter 环境配置的完整速查手册。建议收藏本文，后续遇到版本切换、镜像配置或命令遗忘时直接检索即可。

FVM 与 Flutter 环境配置完全指南：从安装到日常使用