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

概述

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

官方网站: fvm.app

为什么需要FVM？

常见问题

1. 版本冲突：不同项目需要不同版本的Flutter
2. 团队协作困难：团队成员使用不同版本导致兼容性问题
3. 环境配置复杂：频繁切换版本需要重新配置环境
4. 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:  /Users/jianguo/fvm/versions
Directory Size: 0 B

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

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

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

mkdir -p /Users/jianguo/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 /Users/jianguo/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创建鸿蒙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. 创建目录和文件

1. 打开项目目录：在VSCode中打开你的项目目录
2. 创建.vscode目录：如果项目目录下没有.vscode目录，可以在项目根目录下手动创建一个名为.vscode的文件夹
3. 创建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. 验证配置

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

1. 打开VSCode集成终端：按下`Ctrl + ``（反引号）打开终端
2. 运行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版本

解决方案：

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

最佳实践

1. 版本管理策略

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

2. 缓存管理

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

3. 开发流程

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

总结

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

主要优势

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

下一步

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

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

相关资源

• FVM官方网站
• FVM GitHub仓库
• 鸿蒙Flutter官方文档
• Flutter官方文档

本文由GitCode深圳团队输出。