FVM 与 Flutter 环境配置完全指南从安装到日常使用本文整理自 Flutter 多版本管理工具 FVM 的官方文档与社区实践覆盖安装配置、常用命令、环境变量与国内镜像加速适合作为日常速查手册收藏。一、FVM 是什么为什么值得用在 Flutter 开发中不同项目往往依赖不同版本的 Flutter SDK。手动切换全局 SDK 不仅低效还容易导致团队协作时版本不一致。FVMFlutter Version Management正是为解决这一问题而设计的工具。FVM 的核心能力包括项目级版本控制每个项目可锁定独立的 Flutter SDK 版本互不干扰快速切换版本切换无需重新下载 SDK秒级完成团队一致性通过.fvmrc文件记录项目版本团队成员一键还原缓存可视化清晰查看哪些 SDK 被使用、哪些未被引用便于清理二、安装 FVM2.1 前置条件建议先按 Flutter 官方安装指南全局安装一个 Flutter SDK作为机器上的“主版本”。FVM 则用于管理各项目的特定版本。2.2 安装方式方式一Dart Pub 全局激活跨平台通用前提是系统中已有可用的dart命令通常随 Flutter 一起安装。dart pub global activate fvm安装后需确保 Dart 全局包的 bin 目录已加入系统 PATH。Windows 下该目录通常为C:\Users\用户名\AppData\Local\Pub\Cache\binmacOS/Linux 下通常为~/.pub-cache/bin方式二HomebrewmacOS/Linuxbrewinstallfvm方式三ChocolateyWindowschoco install fvm方式四独立安装脚本推荐curl-fsSLhttps://fvm.app/install.sh|bash如需指定版本curl -fsSL https://fvm.app/install.sh | bash -s -- version2.3 验证安装关闭当前终端重新打开后执行fvm--version若提示“command not found”请检查 FVM 的安装目录是否已加入 PATH。三、FVM 常用命令速查3.1 版本安装与切换命令作用示例fvm install [version]下载并缓存指定 Flutter 版本fvm install 3.22.0fvm install根据项目.fvmrc安装对应版本fvm installfvm use [version]为当前项目锁定 Flutter 版本fvm use 3.22.0fvm use stable --pin锁定当前 stable 最新版fvm use stable --pinfvm global [version]设置全局默认 Flutter 版本fvm global 3.22.0fvm remove [version]删除指定版本 SDKfvm remove 3.19.0fvm destroy清空 FVM 所有缓存fvm destroyfvm use执行后会在项目根目录生成.fvmrc文件并创建.fvm/flutter_sdk符号链接。.fvmrc应提交到 Git确保团队一致。3.2 版本查看与管理命令作用fvm list/fvm ls列出已安装的所有 Flutter 版本fvm releases列出可安装的 Flutter 版本需联网fvm cleanup查看可清理的未使用 SDK 和补丁升级fvm cleanup --remove-unused移除未使用的 SDKfvm list会标注每个 SDK 的状态Local被当前目录项目锁定、Global全局默认、Unused无项目引用。Unused仅作为清理提示FVM 不会自动删除。3.3 执行 Flutter/Dart 命令使用 FVM 管理版本后所有 Flutter 命令需加fvm前缀fvm flutter doctor fvm flutter pub get fvm flutter run fvm flutter build apk--releasefvm dart analyze fvm dartformat.FVM 按以下优先级查找 SDK项目.fvmrc→ 全局版本 → 系统 PATH 中的 Flutter。3.4 临时使用特定版本fvm spawn3.22.0test该命令使用指定版本执行一次操作不改变项目的锁定版本。四、环境变量配置4.1 必须配置的环境变量方法一当前会话临时设置PowerShell 语法在 PowerShell 中临时设置环境变量用$env:前缀$env:PUB_HOSTED_URLhttps://mirrors.cloud.tencent.com/dart-pub$env:FLUTTER_STORAGE_BASE_URLhttps://mirrors.cloud.tencent.com/flutter$env:FVM_FLUTTER_URLhttps://gitee.com/mirrors/Flutter.git注意这种方式只在当前 PowerShell 窗口有效关闭窗口后失效。方法二永久设置推荐用户级使用[Environment]::SetEnvironmentVariable写入系统环境变量[Environment]::SetEnvironmentVariable(PUB_HOSTED_URL,https://mirrors.cloud.tencent.com/dart-pub,User)[Environment]::SetEnvironmentVariable(FLUTTER_STORAGE_BASE_URL,https://mirrors.cloud.tencent.com/flutter,User)[Environment]::SetEnvironmentVariable(FVM_FLUTTER_URL,https://gitee.com/mirrors/Flutter.git,User)设置完后需要重启终端或新开一个 PowerShell 窗口才会生效。方法三用 setx 命令永久但当前窗口不生效setx PUB_HOSTED_URLhttps://mirrors.cloud.tencent.com/dart-pubsetx FLUTTER_STORAGE_BASE_URLhttps://mirrors.cloud.tencent.com/fluttersetx FVM_FLUTTER_URLhttps://gitee.com/mirrors/Flutter.gitsetx也是写入永久环境变量但当前窗口不会立即生效需要重开终端。验证是否设置成功echo$env:PUB_HOSTED_URLecho$env:FLUTTER_STORAGE_BASE_URLecho$env:FVM_FLUTTER_URL其中两个变量是用于让 Flutter 和 Dart Pub 从国内镜像下载资源国内开发者强烈建议配置变量名用途推荐值PUB_HOSTED_URLDart 包仓库地址https://pub.flutter-io.cnFLUTTER_STORAGE_BASE_URLFlutter 二进制资源地址https://storage.flutter-io.cnWindowsPowerShell 永久设置[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中添加exportPUB_HOSTED_URLhttps://pub.flutter-io.cnexportFLUTTER_STORAGE_BASE_URLhttps://storage.flutter-io.cn然后source ~/.zshrc生效。4.2 FVM 专用环境变量变量名用途说明FVM_FLUTTER_URL自定义 Flutter SDK 的 Git 仓库地址国内加速关键变量FVM_CACHE_PATH自定义 FVM 缓存目录默认~/.fvmFVM_GIT_CACHE_PATHGit 缓存位置可加速重复下载FVM_FLUTTER_URL国内镜像推荐值exportFVM_FLUTTER_URLhttps://gitee.com/mirrors/Flutter.git或使用清华 TUNA 镜像exportFVM_FLUTTER_URLhttps://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.gitFVM 默认从 GitHub 拉取 Flutter SDK国内访问不稳定。设置此变量后fvm install会改从国内镜像拉取。Windows 设置方式[System.Environment]::SetEnvironmentVariable(FVM_FLUTTER_URL,https://gitee.com/mirrors/Flutter.git,User)五、国内镜像加速完整方案5.1 镜像源对比镜像源PUB_HOSTED_URLFLUTTER_STORAGE_BASE_URL特点腾讯云https://mirrors.cloud.tencent.com/dart-pubhttps://mirrors.cloud.tencent.com/flutter稳定社区推荐阿里云https://mirrors.aliyun.com/dart-pubhttps://mirrors.aliyun.com/flutter更新频率高上海交大https://mirror.sjtu.edu.cn/dart-pubhttps://mirror.sjtu.edu.cn教育网友好CFUGhttps://pub.flutter-io.cnhttps://storage.flutter-io.cnFlutter 中文社区维护5.2 推荐配置组合# Dart 包镜像腾讯云exportPUB_HOSTED_URLhttps://mirrors.cloud.tencent.com/dart-pub# Flutter 资源镜像腾讯云exportFLUTTER_STORAGE_BASE_URLhttps://mirrors.cloud.tencent.com/flutter# FVM 拉取 SDK 的 Git 镜像GiteeexportFVM_FLUTTER_URLhttps://gitee.com/mirrors/Flutter.git这一组合在社区中被广泛验证兼顾速度与稳定性。5.3 验证配置新开终端后执行echo$env:FLUTTER_STORAGE_BASE_URL# PowerShellecho$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.1fvm命令找不到确认 FVM 安装目录已加入 PATH。Windows 下通常为%LOCALAPPDATA%\Pub\Cache\binmacOS/Linux 下为~/.pub-cache/bin。添加后需新开终端。6.2fvm use后 Flutter 版本未变化检查项目根目录是否存在.fvmrc文件。如果没有说明fvm use未成功执行。在项目目录中重新执行fvm use version。6.3fvm install超时或失败优先检查FVM_FLUTTER_URL是否已设置为国内镜像。未设置时 FVM 会从 GitHub 拉取国内访问容易超时。6.4 安装后fvm list显示 “needs setup”执行以下命令补全 SDK 依赖fvminstallversion--setup--setup会下载 SDK 所需的额外资源确保版本可用。6.5 IDE 识别不到 FVM 管理的 FlutterVS Code 用户可在.vscode/settings.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避免解析歧义八、完整安装流程速览# 1. 安装 FVMdart 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 版本fvminstall3.22.0# 4. 进入项目目录锁定版本cd/path/to/project fvm use3.22.0# 5. 验证fvm flutter--version# 6. 用 FVM 版本执行构建fvm flutter build apk--release以上就是 FVM 与 Flutter 环境配置的完整速查手册。建议收藏本文后续遇到版本切换、镜像配置或命令遗忘时直接检索即可。