Mac Flutter FVM 多版本管理安装与常用指令
本文详细解析了在 Mac 上安装 Flutter 与 FVM 的完整流程,包括安装前需准
记录一次在 Mac 上安装 Flutter 和 FVM 的过程,顺手整理一下 FVM 的常用命令、环境变量配置、国内网络镜像,以及
flutter和fvm flutter的区别。
一、FVM 是什么
FVM 全称是 Flutter Version Management,用来管理多个 Flutter SDK 版本。
为什么需要它?
- 不同项目可能依赖不同 Flutter 版本。
- Flutter 升级比较频繁,直接全局升级容易影响旧项目。
- 团队协作时,可以把项目使用的 Flutter 版本固定下来。
- 新老项目切换时,不需要反复手动替换 Flutter SDK。
简单理解:
flutter是 Flutter SDK 本体。fvm是 Flutter 版本管理器。fvm flutter是通过 FVM 选择的 Flutter 版本执行命令。
二、安装前准备
Mac 上建议先检查下面几个工具是否已经安装好。
| 工具 | 用途 | 检查命令 |
|---|---|---|
| Homebrew | Mac 常用包管理工具,用来安装 FVM、Dart 等命令行工具 | brew --version |
| Dart SDK | Dart 运行环境,使用 dart pub global activate fvm 时需要 |
dart --version |
| Xcode | iOS、macOS 编译、模拟器、证书和上架必备 | xcodebuild -version |
| Android Studio | Android SDK、模拟器、构建工具管理 | 打开 App 检查 |
| VS Code / Cursor | 日常写 Flutter/Dart 代码 | 打开 App 检查 |
1. 安装 Homebrew
如果执行:
bash
brew --version
提示 command not found,说明还没安装 Homebrew。
可以到官网复制最新安装命令:
text
https://brew.sh/
安装完成后重新打开终端,再检查:
bash
brew --version
Apple Silicon 芯片的 Mac 通常会安装到:
bash
/opt/homebrew
如果安装后仍然找不到 brew,可以把下面内容加入 ~/.zshrc:
bash
eval "$(/opt/homebrew/bin/brew shellenv)"
然后刷新:
bash
source ~/.zshrc
2. 安装 Dart SDK
如果执行:
bash
dart --version
能看到版本号,说明 Dart SDK 已经可用。
如果提示 command not found,可以通过 Homebrew 安装:
bash
brew tap dart-lang/dart
brew install dart
安装完成后检查:
bash
dart --version
注意:如果你后面直接安装完整 Flutter SDK,Flutter 自身也会带 Dart SDK;但如果你想用:
bash
dart pub global activate fvm
这种方式安装 FVM,就需要先有可用的 dart 命令。
3. 安装 Xcode
如果需要开发 iOS 或 macOS App,Xcode 必装。
安装方式:
- 打开 Mac App Store。
- 搜索 Xcode。
- 安装并启动一次。
安装完成后执行:
bash
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
xcodebuild -version
如果后面 Flutter 检查提示 CocoaPods 缺失,可以再安装:
bash
sudo gem install cocoapods
4. 安装 Android Studio
如果需要开发 Android App,Android Studio 必装。
下载地址:
text
https://developer.android.com/studio
安装后打开 Android Studio,建议确认这些内容:
- Android SDK
- Android SDK Platform
- Android SDK Command-line Tools
- Android Emulator
- 至少创建一个 Android 模拟器
后续安装 Flutter 后,可以执行:
bash
flutter doctor --android-licenses
按提示接受 Android licenses。
5. 安装 VS Code 或 Cursor
日常写 Flutter 代码,可以用 VS Code 或 Cursor。
VS Code 下载地址:
text
https://code.visualstudio.com/
Cursor 下载地址:
text
https://cursor.com/
安装后建议在插件市场安装:
- Flutter
- Dart
如果你已经能正常执行:
bash
brew --version
dart --version
xcodebuild -version
并且 Android Studio、VS Code 或 Cursor 都能打开,基础准备就差不多了。
三、安装 FVM
FVM 常见有两种安装方式。
方式一:使用 Homebrew 安装
bash
brew tap leoafarias/fvm
brew install fvm
如果之前已经 tap 过,也可以直接:
bash
brew install fvm
方式二:使用 Dart Pub 安装
bash
dart pub global activate fvm
如果 Homebrew 安装卡在 dart pub get 或访问 pub.dev 失败,可以优先尝试这种方式。
四、国内网络镜像配置
在国内安装 Flutter、FVM 时,经常会遇到下载很慢,或者访问 pub.dev 失败。
建议先配置镜像环境变量:
bash
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
如果使用 Homebrew 安装,还可以配置 Homebrew 镜像:
bash
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles
export HOMEBREW_API_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles/api
建议写入 ~/.zshrc:
bash
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles
export HOMEBREW_API_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles/api
刷新配置:
bash
source ~/.zshrc
五、配置 PATH
如果通过 Dart Pub 安装 FVM,FVM 可执行文件通常在:
bash
$HOME/.pub-cache/bin
建议在 ~/.zshrc 中加入:
bash
export PATH="$HOME/.pub-cache/bin:$PATH"
如果已经使用 FVM 设置了全局 Flutter 版本,也可以加入:
bash
export PATH="$HOME/fvm/default/bin:$HOME/.pub-cache/bin:$PATH"
然后刷新:
bash
source ~/.zshrc
检查 FVM 是否安装成功:
bash
fvm --version
六、常用命令速查表
| 命令 | 简写 | 说明 | 示例 |
|---|---|---|---|
fvm install <version> |
- | 安装指定 Flutter 版本 | fvm install 3.16.4 |
fvm install stable |
- | 安装稳定版 | fvm install stable |
fvm install beta |
- | 安装 beta 版 | fvm install beta |
fvm use <version> |
- | 当前项目使用指定版本 | fvm use stable |
fvm global <version> |
- | 设置全局默认版本 | fvm global stable |
fvm list |
fvm ls |
查看已安装版本 | fvm ls |
fvm releases |
fvm list-remote |
查看可安装版本 | fvm releases |
fvm remove <version> |
fvm rm |
删除已安装版本 | fvm rm 3.10.0 |
fvm flutter <command> |
fvm fl |
使用当前项目 Flutter 执行命令 | fvm flutter run |
fvm dart <command> |
- | 使用当前项目 Dart 执行命令 | fvm dart pub get |
fvm cache clean |
- | 清理下载缓存 | fvm cache clean |
fvm config |
- | 查看 FVM 配置 | fvm config |
fvm --version |
fvm -v |
查看 FVM 版本 | fvm -v |
七、安装 Flutter 版本
安装稳定版:
bash
fvm install stable
安装指定版本:
bash
fvm install 3.44.6
安装 beta 版本:
bash
fvm install beta
查看已安装版本:
bash
fvm list
输出示例:
text
Cache directory: /Users/chenxiangwen/fvm/versions
Directory Size: 1.17 GB
┌─────────┬─────────┬─────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version │ Channel │ Flutter Version │ Dart Version │ Release Date │ Global │ Local │
├─────────┼─────────┼─────────────────┼──────────────┼──────────────┼────────┼───────┤
│ stable │ stable │ 3.44.6 │ 3.12.2 │ Jul 9, 2026 │ │ │
└─────────┴─────────┴─────────────────┴──────────────┴──────────────┴────────┴───────┘
其中带 global 的版本表示全局默认版本。
八、项目中使用指定 Flutter 版本
进入项目目录:
bash
cd your_flutter_project
指定项目使用稳定版:
bash
fvm use stable
或者指定具体版本:
bash
fvm use 3.44.6
执行后,项目中会生成 .fvm 目录,记录当前项目使用的 Flutter 版本。
之后在项目里建议使用:
bash
fvm flutter pub get
fvm flutter run
fvm flutter build apk
fvm flutter build ios
九、全局版本和项目版本的区别
这是使用 FVM 最容易搞混的地方。
1. flutter --version
bash
flutter --version
这个命令使用的是当前 PATH 中优先找到的 Flutter。
如果你配置了:
bash
export PATH="$HOME/fvm/default/bin:$PATH"
那么 flutter 使用的通常是:
bash
fvm global <version>
设置的全局版本。
2. fvm flutter --version
bash
fvm flutter --version
这个命令会优先使用当前项目 .fvm 配置的版本。
也就是说:
flutter run:使用全局 Flutter,或者 PATH 中优先找到的 Flutter。fvm flutter run:使用当前项目指定的 Flutter。
项目开发中更推荐使用:
bash
fvm flutter run
这样不会因为全局 Flutter 版本变化影响项目。
十、常见问题
1. fvm: command not found
说明 FVM 没有加入 PATH。
检查:
bash
ls ~/.pub-cache/bin/fvm
如果存在,加入 PATH:
bash
export PATH="$HOME/.pub-cache/bin:$PATH"
source ~/.zshrc
2. Homebrew 安装 FVM 时访问 pub.dev 失败
错误类似:
text
Got socket error trying to find package xxx at https://pub.dev.
先配置:
bash
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
然后重新安装:
bash
brew reinstall fvm
或者直接改用 Dart Pub:
bash
dart pub global activate fvm
3. brew install --cask flutter 和 FVM 有什么区别
bash
brew install --cask flutter
安装的是完整 Flutter SDK 本体,下载包会很大。
bash
brew install fvm
安装的是 Flutter 版本管理器,不是 Flutter SDK 本体。
如果是第一次接触 Flutter,直接安装 Flutter SDK 更简单;如果后续要多个项目共存,建议使用 FVM 管理版本。
4. 安装版本时没反应或很慢
优先检查网络和镜像配置:
bash
echo $PUB_HOSTED_URL
echo $FLUTTER_STORAGE_BASE_URL
如果为空,先设置镜像。
如果仍然很慢,换网络或开启代理再试。
十一、推荐日常工作流
新项目:
bash
fvm install stable
fvm use stable
fvm flutter create .
fvm flutter pub get
fvm flutter run
已有项目:
bash
cd your_flutter_project
fvm use stable
fvm flutter pub get
fvm flutter run
查看环境:
bash
fvm flutter doctor
构建 Android:
bash
fvm flutter build apk
构建 iOS:
bash
fvm flutter build ios
十二、总结
FVM 的核心价值是让 Flutter 版本可控。
记住这几个点就够了:
fvm install stable:安装 Flutter 稳定版。fvm use stable:当前项目使用稳定版。fvm global stable:设置全局默认版本。fvm flutter run:使用当前项目 Flutter 运行。flutter run:使用全局 Flutter,可能不是项目指定版本。
开发项目时,尽量使用:
bash
fvm flutter <command>
这样最稳。