企业官网建设流程全解析

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 一起安装）。

dart pub global activate fvm

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

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

macOS/Linux 下通常为：

~/.pub-cache/bin

方式二：Homebrew（macOS/Linux）

brewinstallfvm

方式三：Chocolatey（Windows）

choco install fvm

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

curl-fsSLhttps://fvm.app/install.sh|bash

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

2.3 验证安装

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

fvm--version

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

三、FVM 常用命令速查

3.1 版本安装与切换

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

3.2 版本查看与管理

fvm 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_URL="https://mirrors.cloud.tencent.com/dart-pub"$env:FLUTTER_STORAGE_BASE_URL="https://mirrors.cloud.tencent.com/flutter"$env:FVM_FLUTTER_URL="https://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_URL"https://mirrors.cloud.tencent.com/dart-pub"setx FLUTTER_STORAGE_BASE_URL"https://mirrors.cloud.tencent.com/flutter"setx FVM_FLUTTER_URL"https://gitee.com/mirrors/Flutter.git"

setx也是写入永久环境变量，但当前窗口不会立即生效，需要重开终端。

验证是否设置成功

echo$env:PUB_HOSTED_URLecho$env:FLUTTER_STORAGE_BASE_URLecho$env:FVM_FLUTTER_URL

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

Windows（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中添加：

exportPUB_HOSTED_URL="https://pub.flutter-io.cn"exportFLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

然后source ~/.zshrc生效。

4.2 FVM 专用环境变量

FVM_FLUTTER_URL国内镜像推荐值：

exportFVM_FLUTTER_URL="https://gitee.com/mirrors/Flutter.git"

或使用清华 TUNA 镜像：

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

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

Windows 设置方式：

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

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

5.1 镜像源对比

5.2 推荐配置组合

# Dart 包镜像（腾讯云）exportPUB_HOSTED_URL="https://mirrors.cloud.tencent.com/dart-pub"# Flutter 资源镜像（腾讯云）exportFLUTTER_STORAGE_BASE_URL="https://mirrors.cloud.tencent.com/flutter"# FVM 拉取 SDK 的 Git 镜像（Gitee）exportFVM_FLUTTER_URL="https://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\bin

macOS/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 依赖：

fvminstall<version>--setup

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

6.5 IDE 识别不到 FVM 管理的 Flutter

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

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

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

七、最佳实践清单

八、完整安装流程速览

# 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 环境配置的完整速查手册。建议收藏本文，后续遇到版本切换、镜像配置或命令遗忘时直接检索即可。