鸿蒙版 Flutter 版本管理利器：FVM 使用指南

peksmart · October 5, 2025, 12:13pm

FVM（Flutter Version Manager）是一个专门为 Flutter 应用开发设计的版本管理工具。它允许开发者在同一台机器上安装和管理多个 Flutter 版本，解决了团队协作和项目迁移时因 Flutter 版本差异导致的兼容性问题。

官方网站: fvm.app^[1]

为什么需要 FVM？

常见问题

版本冲突：不同项目需要不同版本的 Flutter
团队协作困难：团队成员使用不同版本导致兼容性问题
环境配置复杂：频繁切换版本需要重新配置环境
CI/CD 不稳定：构建环境版本不一致导致部署失败

FVM 的解决方案

多版本管理：同时管理多个 Flutter 版本
版本隔离：每个项目使用独立的 Flutter 环境
团队协作：确保团队成员使用相同版本
简化配置：自动管理 SDK 下载和切换

核心功能

1. 多版本管理

支持安装管理多种 Flutter SDK 版本
包括稳定版、Beta 版、Dev 版及自定义版本
根据项目需求快速切换版本

2. 版本隔离

为每个项目创建独立 Flutter 环境
不同项目使用的版本互不干扰
便于维护多版本项目

3. 团队协作支持

团队成员使用相同版本开发
避免版本不一致导致的错误
指定项目所需版本，成员易于复现环境

4. 全局与项目级配置

设置全局默认 Flutter 版本
为特定项目设置专用版本
提供灵活的配置选项

5. 命令行工具

提供丰富的命令行工具：

查看版本：fvm list
安装版本：fvm install
设置全局版本：fvm global
项目内使用特定版本：fvm use
移除版本：fvm remove
清理缓存：fvm cache clean

优势

提高开发效率：快速切换版本，减少环境配置时间
降低环境配置复杂度：自动管理 SDK 下载、安装和切换
增强项目可移植性：项目绑定特定版本，确保一致性
支持 CI/CD 集成：无缝集成到持续集成和持续部署流程

准备工作

检查 FVM 缓存目录

首先检查 FVM 的缓存目录状态：

fvm list

如果显示如下信息，说明缓存目录为空：

Cache directory:  C:\Users\Admin\fvm\versions
Directory Size: 0 B

No SDKs have been installed yet. Flutter SDKs
installed outside of fvm will not be displayed.

创建缓存目录（如果需要）

如果缓存目录不存在，需要手动创建：

mkdir -p C:\Users\Admin\fvm\versions

安装 FVM

方法一：使用包管理器安装（推荐）

macOS 用户

brew install fvm

Windows 用户

choco install fvm

Linux 用户

sudo snap install fvm

方法二：使用 Dart 全局安装

dart pub global activate fvm

方法三：从源码安装

git clone https://github.com/leoafarias/fvm.git
cd fvm
dart pub global activate --source path .

配置和验证

检查 FVM 状态

安装完成后，运行以下命令检查 FVM 配置：

fvm doctor

该命令会检查 FVM 的配置状态，并提示是否需要更新或修复。

更新 FVM

如需更新 FVM 到最新版本：

dart pub global activate fvm

验证安装

fvm --version

如果显示版本信息，说明安装成功。

配置鸿蒙版 Flutter 版本

鸿蒙版 Flutter 版本说明

鸿蒙版 Flutter 有多个版本分支，每个版本都有特定的功能和兼容性：

版本	分支	仓库地址	说明
3.22.1	3.22.0-ohos	openharmony-tpc	稳定版本
3.27.4	oh-3.27.4-dev	openharmony-tpc	开发版本
3.32.4	oh-3.32.4-dev	openharmony-tpc	最新版本

配置步骤

1. 克隆鸿蒙版 Flutter 源码

根据需要的版本选择对应的命令：

配置 3.22.1 版本：

git clone --branch 3.22.0-ohos git@gitcode.com:openharmony-tpc/flutter_flutter.git custom_3.22.1

配置 3.27.4 版本：

git clone --branch oh-3.27.4-dev git@gitcode.com:openharmony-tpc/flutter_flutter.git custom_3.27.4

配置 3.32.4 版本：

git clone --branch oh-3.32.4-dev git@gitcode.com:openharmony-tpc/flutter_flutter.git custom_3.32.4

2. 将版本添加到 FVM

克隆完成后，需要将版本添加到 FVM 的缓存目录：

# 将克隆的版本移动到FVM缓存目录
mv custom_3.22.1 C:\Users\Admin\fvm\versions

3. 验证版本

fvm list

应该能看到新添加的版本。

使用 FVM 管理版本

实际配置示例

以配置 3.32.4 版本为例，演示完整的配置过程：

1. 克隆特定版本

git clone --branch oh-3.32.4-dev git@gitcode.com:openharmony-tpc/flutter_flutter.git  custom_3.32.4

2. 查看 FVM 状态

fvm list

初始状态显示：

Cache directory:  /Users/jianguo/fvm/versions
Directory Size: 1.87 GB

┌───────────────┬─────────┬─────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version       │ Channel │ Flutter Version │ Dart Version │ Release Date │ Global │ Local │
├───────────────┼─────────┼─────────────────┬──────────────┼──────────────┼────────┼───────┤
│ custom_3.32.4 │         │ Need setup      │              │              │        │       │
└───────────────┴─────────┴─────────────────┴──────────────┴──────────────┴────────┴───────┘

3. 设置版本

fvm use custom_3.32.4

系统会提示：

[WARN] Not checking for version mismatch as custom version is being used.

No pubspec.yaml detected in this directory
✔ Would you like to continue? · yes

4. 下载和配置 SDK

FVM 会自动下载所需的 Dart SDK：

Downloading Darwin arm64 Dart SDK from Flutter engine 2d7bb04571c712838a076cd26a74455d6a91d42e...
dart-sdk-url: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/2d7bb04571c712838a076cd26a74455d6a91d42e/dart-sdk-darwin-arm64.zip
  % Total    % Received   Xferd  Average Speed   Time    Time     Time    Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  122M  100  122M    0     0  1548k      0  0:01:21  0:01:21 --:--:-- 1416k
Building flutter tool...
Resolving dependencies... (1.4s)
Downloading packages...
Got dependencies.
Flutter 3.22.1-ohos-1.0.0 • channel [user-branch] • git@gitcode.com:openharmony-tpc/flutter_flutter.git
Framework • revision b4fecf02f5 (4 days ago) • 2025-05-08 11:47:56 +0800
Engine • revision f6344b75dc
Tools • Dart 3.4.0 • DevTools 2.34.1

5. 验证配置

配置完成后，再次查看 FVM 状态：

fvm list

显示结果：

Cache directory:  /Users/jianguo/fvm/versions
Directory Size: 2.27 GB

┌───────────────┬─────────┬───────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version       │ Channel │ Flutter Version   │ Dart Version │ Release Date │ Global │ Local │
├───────────────┼─────────┼───────────────────┬──────────────┼──────────────┼────────┼───────┤
│ custom_3.22.1 │         │ 3.22.1-ohos-1.0.0 │ 3.4.0        │              │        │       │
└───────────────┴─────────┴───────────────────┴──────────────┴──────────────┴────────┴───────┘

FVM配置成功

创建项目

使用 FVM 创建鸿蒙 Flutter 项目

SDK 下载到缓存目录后，可以使用 FVM 来创建项目：

# 创建项目目录
mkdir my_harmony_flutter_app
cd my_harmony_flutter_app

# 使用自定义SDK
# 由于此时项目目录是空的，可能会提示是否继续，一路yes即可
fvm use custom_3.22.1

# 创建项目，不要忽略最后的那个"."哦
fvm flutter create --platforms=ohos --project-name demo .

项目结构

创建后，目录中会出现以下文件：

.fvm：软链接到 SDK 实际位置
.fvmrc：配置文件
pubspec.yaml：项目配置文件

执行tree -L 2 .fvm查看结构：

.fvm
├── flutter_sdk -> /Users/jianguo/fvm/versions/custom_3.22.1
├── fvm_config.json
├── release
├── version
└── versions
    └── custom_3.22.1 -> /Users/jianguo/fvm/versions/custom_3.22.1

4 directories, 3 files

可以发现，其中.fvm/flutter_sdk和.fvm/versions下的文件均软链接到 SDK 实际缓存位置，实现复用。

IDE 配置

VSCode 配置

在项目目录下的.vscode/settings.json里配置 SDK 位置：

{
  "dart.flutterSdkPath": ".fvm/versions/custom_3.22.1",
  "dart.addSdkToTerminalPath": true,
  "dart.env": {
    "PUB_HOSTED_URL": "https://pub.flutter-io.cn"
  }
}

创建 VSCode 配置文件

如果没有找到.vscode/settings.json文件，可以按照以下步骤创建：

1. 创建目录和文件

打开项目目录：在 VSCode 中打开你的项目目录
创建.vscode目录：如果项目目录下没有.vscode目录，可以在项目根目录下手动创建一个名为.vscode的文件夹
创建settings.json文件：在.vscode目录下创建一个名为settings.json的文件

2. 配置内容

在settings.json文件中，添加以下内容来配置 SDK 路径：

{
  "dart.flutterSdkPath": ".fvm/versions/custom_3.22.1",
  "dart.addSdkToTerminalPath": true,
  "dart.env": {
    "PUB_HOSTED_URL": "https://pub.flutter-io.cn"
  }
}

3. 配置项说明

dart.flutterSdkPath：指定 Flutter SDK 的路径。这里使用.fvm/versions/custom_3.22.1，这是 FVM 管理的 Flutter SDK 的路径
dart.addSdkToTerminalPath：将当前项目的 Flutter SDK 添加到 VSCode 集成终端的 PATH 环境变量中，这样你可以在终端中直接使用 Flutter 命令
dart.env：设置环境变量，这里配置了PUB_HOSTED_URL为国内的镜像地址，可以加快包的下载速度

4. 验证配置

完成配置后，可以通过以下步骤验证配置是否正确：

打开 VSCode 集成终端：按下`Ctrl + ``（反引号）打开终端
运行 Flutter 命令：输入flutter --version，检查是否显示的是你配置的 Flutter 版本

如果显示的版本与你配置的版本一致，说明配置成功。

验证 FVM 配置

jianguo@nutpi fvmdemo % fvm flutter --version
[WARN] Not checking for version mismatch as custom version is being used.
Flutter 3.27.4-ohos-0.0.1 • channel [user-branch] •
git@gitcode.com:hezySign/flutter_flutter.git
Framework • revision a64b6af3de (3 days ago) • 2025-05-20 20:25:43 +0800
Engine • revision e672b006cb
Tools • Dart 3.6.2 • DevTools 2.40.0

  ╔═══════════════════════════════════════════════════════════════════════
  ═════╗
  ║                 Welcome to Flutter! - https://flutter.dev
  ║
  ║
  ║
  ║ The Flutter tool uses Google Analytics to anonymously report feature
  ║ usage ║
  ║ statistics and basic crash reports. This data is used to help improve
  ║
  ║ Flutter tools over time.
  ║
  ║
  ║
  ║ Flutter tool analytics are not sent on the very first run. To disable
  ║
  ║ reporting, type'flutter config --no-analytics'. To display the
  ║ current    ║
  ║ setting, type'flutter config'. If you opt out of analytics, an
  ║ opt-out    ║
  ║ event will be sent, and then no further information will be sent by
  ║ the    ║
  ║ Flutter tool.
  ║
  ║
  ║
  ║ By downloading the Flutter SDK, you agree to the Google Terms of
  ║ Service.  ║
  ║ The Google Privacy Policy describes how data is handled in this
  ║ service.   ║
  ║
  ║
  ║ Moreover, Flutter includes the Dart SDK, which may send usage metrics
  ║ and  ║
  ║ crash reports to Google.
  ║
  ║
  ║
  ║ Read about data we send with crash reports:
  ║
  ║ https://flutter.dev/to/crash-reporting
  ║
  ║
  ║
  ║ See Google's privacy policy:
  ║
  ║ https://policies.google.com/privacy
  ║
  ║
  ║
  ║ To disable animations in this tool, use
  ║
  ║ 'flutter config --no-cli-animations'.
  ║
  ╚═══════════════════════════════════════════════════════════════════════
  ═════╝

常用命令

FVM 基本命令

# 查看已安装的版本
fvm list

# 安装指定版本
fvm install 3.22.1

# 设置全局版本
fvm global 3.22.1

# 在项目中设置版本
fvm use 3.22.1

# 移除版本
fvm remove 3.22.1

# 清理缓存
fvm cache clean

# 检查FVM状态
fvm doctor

Flutter 命令

# 使用FVM管理的Flutter版本
fvm flutter --version
fvm flutter doctor
fvm flutter create my_app
fvm flutter run
fvm flutter build

故障排除

常见问题

1. 版本显示"Need setup"

问题：FVM list 显示版本状态为"Need setup"

解决方案：

# 进入版本目录
cd /Users/jianguo/fvm/versions/custom_3.22.1

# 运行Flutter doctor
./bin/flutter doctor

2. 权限问题

问题：无法创建或修改文件

解决方案：

# 检查目录权限
ls -la /Users/jianguo/fvm/versions/

# 修改权限
chmod -R 755 /Users/jianguo/fvm/versions/

3. 网络问题

问题：下载 SDK 失败

解决方案：

# 使用国内镜像
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# 重新尝试
fvm use custom_3.22.1

4. IDE 不识别 FVM 版本

问题：VSCode 等 IDE 无法识别 FVM 管理的 Flutter 版本

解决方案：

检查.vscode/settings.json配置
重启 IDE
确保路径正确

最佳实践

1. 版本管理策略

项目级配置：为每个项目指定特定的 Flutter 版本
团队协作：使用.fvmrc文件确保团队成员使用相同版本
版本命名：使用有意义的版本名称，如custom_3.22.1

2. 缓存管理

定期清理：定期运行fvm cache clean清理不需要的版本
磁盘空间：监控 FVM 缓存目录的磁盘使用情况
备份重要版本：备份项目中使用的关键版本

3. 开发流程

版本锁定：在项目中使用fvm use锁定版本
CI/CD 集成：在构建脚本中使用 FVM 确保版本一致性
文档记录：在 README 中记录项目使用的 Flutter 版本

总结

FVM 是 Flutter 开发者不可或缺的工具，它极大简化了 Flutter 版本管理的复杂性，提高了团队协作效率。无论是个人开发者还是大型团队，FVM 都能提供强大的支持。

主要优势

简化版本管理：轻松安装、切换和管理多个 Flutter 版本
提高开发效率：快速切换版本，减少环境配置时间
增强团队协作：确保团队成员使用相同的 Flutter 版本
支持鸿蒙开发：完美支持鸿蒙版 Flutter 的版本管理
IDE 集成：与 VSCode 等主流 IDE 无缝集成

下一步

安装 FVM 并配置鸿蒙版 Flutter 版本
创建第一个使用 FVM 管理的项目
配置 IDE 以使用 FVM 管理的 Flutter 版本
在团队中推广 FVM 的使用

希望这篇指南能帮助你轻松掌握 FVM 的使用方法，让 Flutter 开发变得更加高效和顺畅！

鸿蒙版 Flutter 版本管理利器：FVM 使用指南

为什么需要 FVM？

常见问题

FVM 的解决方案

核心功能

1. 多版本管理

2. 版本隔离

3. 团队协作支持

4. 全局与项目级配置

5. 命令行工具

优势

准备工作

检查 FVM 缓存目录

创建缓存目录（如果需要）

安装 FVM

方法一：使用包管理器安装（推荐）

macOS 用户

Windows 用户

Linux 用户

方法二：使用 Dart 全局安装

方法三：从源码安装

配置和验证

检查 FVM 状态

更新 FVM

验证安装

配置鸿蒙版 Flutter 版本

鸿蒙版 Flutter 版本说明

配置步骤

1. 克隆鸿蒙版 Flutter 源码

2. 将版本添加到 FVM

3. 验证版本

使用 FVM 管理版本

实际配置示例

1. 克隆特定版本

2. 查看 FVM 状态

3. 设置版本

4. 下载和配置 SDK

5. 验证配置

创建项目

使用 FVM 创建鸿蒙 Flutter 项目

项目结构

IDE 配置

VSCode 配置

创建 VSCode 配置文件

1. 创建目录和文件

2. 配置内容

3. 配置项说明

4. 验证配置

验证 FVM 配置

常用命令

FVM 基本命令

Flutter 命令

故障排除

常见问题

1. 版本显示"Need setup"

2. 权限问题

3. 网络问题

4. IDE 不识别 FVM 版本

最佳实践

1. 版本管理策略

2. 缓存管理

3. 开发流程

总结

主要优势

下一步

相关资源