Flutter - 多版本管理工具FVM

FVM 使用详情（Flutter SDK 管理工具）

本文系统介绍 FVM（Flutter Version Management），帮助你在单机与团队项目中稳定、可控地管理多个 Flutter SDK 版本，提升切换效率与协作一致性。

适用读者：Flutter 开发者、团队工程负责人、CI/CD 管线维护者
操作系统：以 macOS 为示例（同时兼顾 Windows 与 Linux 注意点）
官方文档参考：见文末「参考资料」

什么是 FVM

FVM 是一个命令行工具，用于在「项目级」管理 Flutter SDK 版本。通过它，你可以：

为不同项目绑定特定的 Flutter 版本（甚至不同 flavor）
秒级切换并复用缓存，无需反复全量下载
在团队内保证一致的 SDK 版本，避免「只在我电脑可运行」问题
安全试用新版本而不影响生产项目

为什么要用 FVM

多项目与多版本并行开发：不同项目可能依赖不同 Flutter 版本
避免慢速的频道切换与重复安装：FVM 用缓存和软链接快速切换
团队一致性与可追溯性：通过 .fvmrc 固化项目版本，版本一致更可控
CI/CD 更容易：可以在流水线上精准指定 SDK 版本

核心概念与目录结构

.fvm/：项目内 FVM 的工作目录，保存软链接与相关配置
.fvm/flutter_sdk：指向缓存中的目标 Flutter SDK 的软链接
.fvmrc：项目版本配置文件（提交到版本库，保证团队一致）
缓存目录：FVM 会在统一的缓存位置保存已安装的各版本 SDK（可配置路径）

安装 FVM（推荐方式）

以下提供 macOS 的常用安装方法：

使用 Homebrew（简洁稳定）：

bash 复制代码

brew tap leoafarias/fvm

bash 复制代码

brew install fvm

使用官方安装脚本（跨平台通用，自动配置 PATH）：

bash 复制代码

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

查看版本与帮助：

bash 复制代码

fvm --version

bash 复制代码

fvm --help

注意：若你使用安装脚本，PATH 会自动写入到你的 shell 配置（如 ~/.zshrc），从而获得 fvm 命令与代理的 flutter/dart 命令。若 PATH 未生效，请手动 source ~/.zshrc 或重新打开终端。

快速上手（项目内使用）

在项目根目录指定版本（如 stable 或具体版本号）：

bash 复制代码

fvm use stable

安装指定版本到缓存（若未安装，fvm use 会自动安装；也可手动执行）：

bash 复制代码

fvm install 3.19.0

在项目中运行 Flutter 命令（通过 FVM 代理）：

bash 复制代码

fvm flutter doctor

bash 复制代码

fvm flutter pub get

bash 复制代码

fvm flutter run

提示：在项目内优先使用 fvm flutter ... 与 fvm dart ...，确保使用项目绑定版本。直接用系统 flutter 可能绕过项目绑定导致版本不一致。

常用命令详解

查看可用发布版本（默认显示 stable，可筛选频道）：

bash 复制代码

fvm releases

bash 复制代码

fvm releases --channel beta

安装版本到缓存（仅安装，不绑定项目）：

bash 复制代码

fvm install 3.19.0

为当前项目设置版本（并写入 .fvmrc，建立软链接，可选项如下）：

bash 复制代码

fvm use 3.19.0

常见可选项（在 fvm use 后追加）：

--pin：锁定频道当前版本（例如 stable 被固定为当下具体版本，避免后续自动升级）
--skip-setup：跳过 SDK 依赖下载以加速
--skip-pub-get：切换版本后跳过依赖安装
--force：强制绕过项目校验
列出本机缓存的已安装版本：

bash 复制代码

fvm list

结果如下

yaml 复制代码

Cache directory:  /Users/pedro/fvm/versions
Directory Size: 14.58 GB

┌─────────┬─────────┬─────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version │ Channel │ Flutter Version │ Dart Version │ Release Date │ Global │ Local │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.32.8  │ stable  │ 3.32.8          │ 3.8.1        │ Jul 25, 2025 │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.29.3  │ stable  │ 3.29.3          │ 3.7.2        │ Apr 14, 2025 │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.22.3  │ stable  │ 3.22.3          │ 3.4.4        │ Jul 18, 2024 │ ●      │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.19.6  │ stable  │ 3.19.6          │ 3.3.4        │ Apr 17, 2024 │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.16.3  │ stable  │ 3.16.3          │ 3.2.3        │ Dec 6, 2023  │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.13.9  │ stable  │ 3.13.9          │ 3.1.5        │ Oct 25, 2023 │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.10.6  │ stable  │ 3.10.6          │ 3.0.6        │ Jul 12, 2023 │        │       │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.7.12  │ stable  │ 3.7.12          │ 2.19.6       │ Apr 20, 2023 │        │       │
└─────────┴─────────┴─────────────────┴──────────────┴──────────────┴────────┴───────┘

设置机器的全局默认版本（慎用，通常项目内绑定更可控）：

bash 复制代码

fvm global 3.19.0

解除全局版本绑定：

bash 复制代码

fvm global --unlink

移除指定版本的缓存：

bash 复制代码

fvm remove 3.16.0

清空整个 FVM 缓存（危险操作，不可逆）：

bash 复制代码

fvm destroy

运行项目绑定版本的 Flutter 命令（代理）：

bash 复制代码

fvm flutter build apk

运行项目绑定版本的 Dart 命令（代理）：

bash 复制代码

fvm dart --version

使用项目绑定版本执行任意命令（如脚本）：

bash 复制代码

fvm exec echo "using project flutter version"

使用指定版本「临时」运行某条 Flutter 命令（不改项目配置）：

bash 复制代码

fvm spawn 3.19.0 flutter --version

显示 FVM 环境与项目诊断信息（排障常用）：

bash 复制代码

fvm doctor

全局配置（缓存路径、Git 缓存、Flutter 仓库、更新提示等）：

bash 复制代码

fvm config --cache-path "$HOME/.fvm_cache"

Fork 仓库管理（企业自建 Flutter 仓库场景）：

bash 复制代码

fvm fork add mycompany https://example.com/flutter.git

bash 复制代码

fvm install mycompany/stable

bash 复制代码

fvm use mycompany/3.19.0

Flavor 支持（不同环境使用不同 SDK）：

bash 复制代码

fvm flavor staging flutter test

进阶用法与版本选择策略

支持的版本格式与示例（按需选择）
- 频道名：stable、beta、dev、master

bash 复制代码

fvm use stable

精确语义版本：例如 3.19.0

bash 复制代码

fvm use 3.19.0

前缀 v 的版本：例如 v3.19.0

bash 复制代码

fvm use v3.19.0

指定频道来源的版本：例如 3.19.0@beta

bash 复制代码

fvm use 3.19.0@beta

提交哈希：例如短 fa345b1 或长 476ad8a9...

bash 复制代码

fvm use fa345b1

自有 Fork：<fork-alias>/<channel> 或 <fork-alias>/<version>

bash 复制代码

fvm use mycompany/stable

频道与 Pin 策略
- --pin 会把频道（如 stable）固定到当前的具体版本，避免未来自动升级渠道版本（不支持 master 频道）[参考 FVM 文档]。

bash 复制代码

fvm use stable --pin

推荐对生产项目使用精确版本或 stable --pin；对试验项目可用频道（不 pin）以快速跟进。
命令路由优先级
- 项目配置 → 上级目录配置 → FVM 全局设置 → 系统 PATH
- 在项目内始终优先使用 fvm flutter 与 fvm dart 保证版本一致。

API 输出与自动化集成

列出缓存版本（JSON）

bash 复制代码

fvm api list

获取可安装的发布版本（JSON，可筛选频道与数量）

bash 复制代码

fvm api releases --limit 20 --filter-channel stable

输出当前项目配置（JSON）

bash 复制代码

fvm api project -p .

输出 FVM 环境上下文（JSON）

bash 复制代码

fvm api context

这些 JSON 输出便于在脚本或工具中做自动化决策（如选择最近的稳定版或校验项目所需版本是否就绪）。

Flavor 与多环境版本

为特定环境（如 production）绑定版本：

bash 复制代码

fvm use 3.19.0 --flavor production

针对 Flavor 执行命令：

bash 复制代码

fvm flavor production flutter build ipa

同理可为 staging、development 等环境分别设置和执行：

bash 复制代码

fvm use 3.10.0 --flavor development

场景：同一仓库的多模块/多环境构建在不同 Flutter 版本下运行，使用 Flavor 保持隔离。

Fork 仓库（企业场景）

添加企业内自建 Flutter 仓库别名（需 .git 结尾）：

bash 复制代码

fvm fork add mycompany https://example.com/flutter.git

列出配置的 Fork：

bash 复制代码

fvm fork list

移除 Fork：

bash 复制代码

fvm fork remove mycompany

安装并使用 Fork 版本：

bash 复制代码

fvm install mycompany/stable

bash 复制代码

fvm use mycompany/3.19.0

适合企业对上游仓库做定制与加固的场景。

全局配置与缓存优化

修改缓存路径（迁移到更大磁盘或统一位置）：

bash 复制代码

fvm config --cache-path "$HOME/.fvm_cache"

切换 Flutter 源仓库：

bash 复制代码

fvm config --flutter-url https://github.com/flutter/flutter.git

控制 Git 缓存（默认开启以加速）：

bash 复制代码

fvm config --no-use-git-cache

指定 Git 缓存路径：

bash 复制代码

fvm config --git-cache-path "$HOME/.git_cache"

关闭更新提醒：

bash 复制代码

fvm config --no-update-check

缓存占用大时，用 fvm list 查看大小与版本分布，按需 fvm remove <version> 清理；避免直接 fvm destroy。

常见工作流模板

新项目初始化（建议清单）
- fvm use <version>（或 stable --pin）
- 提交 .fvmrc
- .gitignore 添加 .fvm/flutter_sdk
- 配置 VS Code / Android Studio 指向 .fvm/flutter_sdk
- 在项目脚本统一使用 fvm flutter ... / fvm dart ...
项目升级策略（安全演进）
- 在分支或副本上试用新版本：

bash 复制代码

fvm spawn 3.32.8 flutter --version

若兼容性良好，切换到新版本：

bash 复制代码

fvm use 3.32.8

如需稳定频道但避免未来升级：

bash 复制代码

fvm use stable --pin

CI/CD 示例（GitHub Actions 片段）

yaml 复制代码

name: Flutter CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build_and_test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install FVM
        run: curl -fsSL https://fvm.app/install.sh | bash
      - name: Cache Flutter versions (optional)
        uses: actions/cache@v4
        with:
          path: ~/.fvm_cache
          key: fvm-cache-${{ runner.os }}
      - name: Install project Flutter version
        run: fvm install
      - name: Get dependencies
        run: fvm flutter pub get
      - name: Run tests
        run: fvm flutter test

在容器或 root 环境可设置 FVM_ALLOW_ROOT=true；也可用 fvm api 输出做动态版本选择。

更全面的问题排查与思路

PATH 未生效或找不到命令

bash 复制代码

which fvm

若无输出：重新加载 shell 文件（如 source ~/.zshrc），或检查安装脚本是否写入 PATH。
检查 PATH 内容：

bash 复制代码

echo $PATH

flutter 指向了系统全局而非项目版本

bash 复制代码

which flutter

在项目内使用 fvm flutter ...，并修正 IDE 的 SDK 路径为 .fvm/flutter_sdk。
权限与软链接问题（macOS）
- 终端需对项目目录有写权限；必要时调整：

bash 复制代码

chmod -R u+rw .

若在 CI/容器使用 root，设置：

bash 复制代码

export FVM_ALLOW_ROOT=true

网络与 Git 访问问题（公司代理）

bash 复制代码

git config --global http.proxy http://127.0.0.1:7890

bash 复制代码

git config --global https.proxy http://127.0.0.1:7890

或在代理环境禁用 Git 缓存以降低复杂度：

bash 复制代码

fvm config --no-use-git-cache

CocoaPods/ iOS 构建异常

bash 复制代码

pod repo update

bash 复制代码

sudo xcode-select -p

如需切换 Xcode 版本：

bash 复制代码

sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

Android SDK/NDK 不一致

bash 复制代码

sdkmanager --list

使用 ANDROID_HOME 与 PATH 指向正确 SDK，保证 Gradle 插件与 Flutter 版本兼容。
VS Code / Android Studio 配置未生效
- VS Code：settings.json 的 dart.flutterSdkPath 指向 .fvm/flutter_sdk
- Android Studio：Preferences → Flutter → 指向项目内 .fvm/flutter_sdk
fvm doctor 综合检查

bash 复制代码

fvm doctor

用于发现 PATH、项目绑定、IDE 集成与缓存等问题。
缓存过大或版本太多

bash 复制代码

fvm list

选择性清理不再使用的版本：

bash 复制代码

fvm remove 3.13.9

常见报错与解释
- flutter upgrade 在发布版本上被阻止：FVM 设计上建议通过频道或明确版本升级，避免不可控变化。
- Permission denied 创建软链接：检查项目目录权限或在 CI 中确认用户身份。
- pub get 卡死：优先检查代理/网络与镜像源，或切换分支测试是否由依赖冲突导致。

迁移到 FVM 的步骤清单（团队版）

安装并验证 FVM（含 PATH）。
在每个项目执行 fvm use <version>（生产项目建议精确版本或 stable --pin）。
提交 .fvmrc 与更新 .gitignore。
统一 IDE 配置为 .fvm/flutter_sdk。
标准化脚本：统一使用 fvm flutter/fvm dart。
在 CI 中安装并调用 fvm，使用 fvm install + fvm flutter test/build。
制定升级策略（试验分支验证→兼容性通过→更新 .fvmrc）。

Windows / Linux 注意点

Windows
- 推荐使用 Chocolatey 安装：choco install fvm
- PowerShell 需要管理员权限以确保 PATH 更新与软链接权限
- 路径分隔符与权限行为与 macOS 不同，确认 IDE SDK 路径为项目内软链接
Linux
- 使用安装脚本或发行版包管理器，确认 curl、tar、sudo/doas 可用
- 若使用 root 或容器，设置 FVM_ALLOW_ROOT=true 并确保缓存路径可写

小贴士（实用技巧）

快速评估新版本：

bash 复制代码

fvm spawn beta flutter --version

固化频道到具体版本（避免后续隐式升级）：

bash 复制代码

fvm use stable --pin

用 API 驱动脚本智能选择最新稳定版（结合 jq 等工具）：

bash 复制代码

fvm api releases --filter-channel stable

参考资料

FVM 官方命令参考与文档
fvm.app/documentati... [访问日期：2025-11-03]
FVM 安装与 PATH 说明
fvm.app/documentati... [访问日期：2025-11-03]
FVM GitHub 仓库（概览与维护流程）
github.com/leoafarias/... [访问日期：2025-11-03]
深入讲解与实操示例（第三方文章，含 CI/Flavors 等场景）
apidog.com/blog/flutte... [访问日期：2025-11-03]