Flutter macOS 安装文档

张3蜂2026-05-22 8:31

目录

[📋 最终状态](#📋 最终状态)

[🔴 失败情况记录](#🔴 失败情况记录)

[失败 1：Dart SDK ZIP 文件损坏](#失败 1：Dart SDK ZIP 文件损坏)

[失败 2：zshrc PATH 配置错误导致 flutter 命令找不到](#失败 2：zshrc PATH 配置错误导致 flutter 命令找不到)

[失败 3：Android SDK cmdline-tools 缺失](#失败 3：Android SDK cmdline-tools 缺失)

[失败 4：Flutter 要求 Android SDK 36](#失败 4：Flutter 要求 Android SDK 36)

[失败 5：CocoaPods 未安装](#失败 5：CocoaPods 未安装)

[✅ 正确安装步骤](#✅ 正确安装步骤)

[第一步：清理损坏的 Flutter 缓存](#第一步：清理损坏的 Flutter 缓存)

[第二步：修复 .zshrc 配置](#第二步：修复 .zshrc 配置)

[第三步：安装 Android cmdline-tools](#第三步：安装 Android cmdline-tools)

[第四步：接受 Android 许可证并安装 SDK](#第四步：接受 Android 许可证并安装 SDK)

[第五步：安装 CocoaPods](#第五步：安装 CocoaPods)

第六步：验证安装

[📁 最终环境配置](#📁 最终环境配置)

[.zshrc 中 Flutter 相关配置](#.zshrc 中 Flutter 相关配置)

[Flutter 版本信息](#Flutter 版本信息)

已连接设备

[🔧 常用 Flutter 命令](#🔧 常用 Flutter 命令)

[⚠️ 已知警告（可忽略）](#⚠️ 已知警告（可忽略）)

日期： 2026-05-21
系统： macOS 26.4 (Darwin arm64)
Flutter 版本： 3.44.0 (stable)

📋 最终状态

复制代码 
[✓] Flutter (Channel stable, 3.44.0)
[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 26.5)
[✓] Chrome - develop for the web
[✓] Connected device (3 available)
[✓] Network resources

! Doctor found issues in 1 category:
    - Upstream repository 非标准源警告（不影响使用，可忽略）

🔴 失败情况记录

失败 1：Dart SDK ZIP 文件损坏

错误信息：

复制代码 
unzip: cannot find zipfile directory in one of 
/Users/***/development/flutter/bin/cache/dart-sdk-darwin-arm64.zip or
/Users/***/development/flutter/bin/cache/dart-sdk-darwin-arm64.zip.zip
It appears that the downloaded file is corrupt

原因： 之前手动下载的 Flutter 包解压后 dart-sdk 目录存在但内容不完整，或者 ZIP 文件本身损坏。

解决： 删除损坏的缓存文件，重新运行 flutter doctor 让 Flutter 自动重新下载。

复制代码 
rm -rf ~/development/flutter/bin/cache/dart-sdk
rm -rf ~/development/flutter/bin/cache/dart-sdk-darwin-arm64.zip
rm -rf ~/development/flutter/bin/cache/dart-sdk.old
flutter doctor  # 自动重新下载 Dart SDK

失败 2：zshrc PATH 配置错误导致 flutter 命令找不到

问题： .zshrc 中 Flutter PATH 配置重复且格式错误：

复制代码 
# 错误写法（两条 PATH 粘在一起）
export PATH="$PATH:$HOME/development/flutter/bin"export PATH="$HOME/development/flutter/bin:$PATH"

原因： 手动编辑 .zshrc 时换行符丢失，导致两条 export 语句连在一起，shell 无法正确解析。

解决： 清理 .zshrc 中重复错误的配置，重新写入正确的 PATH 配置。

失败 3：Android SDK cmdline-tools 缺失

错误信息：

复制代码 
✗ cmdline-tools component is missing.
Try installing or updating Android Studio.
Alternatively, download the tools from 
https://developer.android.com/studio#command-line-tools-only

原因： Android SDK 缺少命令行工具，Flutter 无法调用 sdkmanager。

解决： 手动下载并安装 Android cmdline-tools：

复制代码 
# 1. 创建 cmdline-tools 目录
mkdir -p ~/Library/Android/sdk/cmdline-tools

# 2. 下载 cmdline-tools
cd ~/Library/Android/sdk/cmdline-tools
curl -o cmdline-tools.zip \
  https://dl.google.com/android/repository/commandlinetools-mac-11076708_latest.zip

# 3. 解压并将目录重命名为 latest（Flutter 要求此目录名）
unzip -o cmdline-tools.zip
mv cmdline-tools latest

失败 4：Flutter 要求 Android SDK 36

错误信息：

复制代码 
✗ Flutter requires Android SDK 36 and the Android BuildTools 28.0.3

原因： Flutter 3.44.0 要求 Android SDK 36，而用户只有 SDK 34。

解决： 使用 sdkmanager 安装所需的 SDK 和 BuildTools：

复制代码 
export LANG=en_US.UTF-8
export PATH="$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH"

# 安装 Android SDK 36 和 BuildTools 28.0.3
yes | sdkmanager "platforms;android-36" "build-tools;28.0.3"

# 接受所有许可证
yes | sdkmanager --licenses

失败 5：CocoaPods 未安装

错误信息：

复制代码 
✗ CocoaPods not installed.
CocoaPods is a package manager for iOS or macOS platform code.
Without CocoaPods, plugins will not work on iOS or macOS.

解决： 通过 Homebrew 安装 CocoaPods：

复制代码 
brew install cocoapods

附带问题： CocoaPods 要求终端使用 UTF-8 编码，需要添加环境变量：

复制代码 
export LANG=en_US.UTF-8

✅ 正确安装步骤

第一步：清理损坏的 Flutter 缓存

复制代码 
rm -rf ~/development/flutter/bin/cache/dart-sdk
rm -rf ~/development/flutter/bin/cache/dart-sdk-darwin-arm64.zip
rm -rf ~/development/flutter/bin/cache/dart-sdk.old
rm -rf ~/development/flutter/bin/cache/dart-sdk

第二步：修复 .zshrc 配置

确保 .zshrc 中包含以下内容（不要有重复或格式错误）：

复制代码 
# Flutter 国内镜像
export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter
export FLUTTER_GIT_URL=https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git
export LANG=en_US.UTF-8
export PATH="$HOME/development/flutter/bin:$PATH"

第三步：安装 Android cmdline-tools

复制代码 
mkdir -p ~/Library/Android/sdk/cmdline-tools
cd ~/Library/Android/sdk/cmdline-tools
curl -o cmdline-tools.zip \
  https://dl.google.com/android/repository/commandlinetools-mac-11076708_latest.zip
unzip -o cmdline-tools.zip
mv cmdline-tools latest

第四步：接受 Android 许可证并安装 SDK

复制代码 
export LANG=en_US.UTF-8
export PATH="$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH"

# 接受所有许可证
yes | sdkmanager --licenses

# 安装所需 SDK
sdkmanager "platforms;android-36" "build-tools;28.0.3"

第五步：安装 CocoaPods

复制代码 
brew install cocoapods

第六步：验证安装

复制代码 
export LANG=en_US.UTF-8
export PATH="$HOME/development/flutter/bin:$PATH"

flutter doctor
flutter --version
flutter devices

📁 最终环境配置

.zshrc 中 Flutter 相关配置

复制代码 
# Flutter 国内镜像
export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter
export FLUTTER_GIT_URL=https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git
export LANG=en_US.UTF-8
export PATH="$HOME/development/flutter/bin:$PATH"

Flutter 版本信息

复制代码 
Flutter 3.44.0 • channel stable
Framework • revision 559ffa3f75 (5 天前)
Engine • hash fcf463a2242790d1fdcd9d044f533080f5022e18
Tools • Dart 3.12.0 • DevTools 2.57.0

已连接设备

|-------------------|----------------|------------|
| 设备 | 类型 | 状态 |
| macOS (desktop) | darwin-arm64 | ✅ 可用 |
| Chrome (web) | web-javascript | ✅ 可用 |
| iPhone (wireless) | iOS 26.5 | ✅ 可用（无线连接） |

🔧 常用 Flutter 命令

复制代码 
# 检查 Flutter 环境
flutter doctor

# 查看 Flutter 版本
flutter --version

# 查看已连接设备
flutter devices

# 查看可用模拟器
flutter emulators

# 升级 Flutter
flutter upgrade

# 创建新项目
flutter create my_app

# 运行应用到设备
flutter run

# 运行应用到 iPhone
flutter run -d "iPhone (wireless)"

# 构建 iOS
flutter build ios

# 构建 Android APK
flutter build apk

# 构建 Web
flutter build web

⚠️ 已知警告（可忽略）

复制代码 
! Upstream repository https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git 
  is not a standard remote.
  Set environment variable "FLUTTER_GIT_URL" to 
  https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git to dismiss this error.

此警告不影响 Flutter 正常使用，已通过添加 FLUTTER_GIT_URL 环境变量抑制（但仍显示警告，Flutter 官方行为）。

相关推荐
月光下的丝瓜1 天前
Flutter 国内安装指南
前端·flutter
Mintimate2 天前
WorkBuddy 上手: 让脚本项目 Homebrew CN 变成会排障的 Agent
macos·边缘计算·agent
恋猫de小郭3 天前
Amper 正式转正 Kotlin Toolchain ，Gradle 未来何去何从
android·前端·flutter
fthux3 天前
如果你用 Mac，那你可能需要 Noti Shift
macos·开源·github
张风捷特烈3 天前
Flutter 类库大揭秘#02 | path_provider 各平台实现
前端·flutter
TT_Close4 天前
别劝退了！5秒搞定 Flutter 鸿蒙 FVM 起跑线
flutter·harmonyos·visual studio code
你听得到114 天前
用户说 App 卡，但说不清在哪？我把 Flutter 监控 SDK 升级成了链路观测工作台
前端·flutter·性能优化
stringwu6 天前
Flutter 开发必备：MVI 架构的高效实现指南
前端·flutter
counterxing6 天前
最近发现一个 Mac 工具，有点像把 Raycast、语音输入法、截图和录屏塞到了一起
macos·ai编程·claude
程序员老刘7 天前
Flutter版本选择指南：3.44系列继续观望 | 2026年6月
flutter·ai编程·客户端
热门推荐
012026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf02GitHub 镜像站点03【AI】2026 年具身智能模型和世界模型总结042026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？052026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？06Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析072026 年 AI 大模型 & AI 编程工具实战全总结082026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？09AI科技热点日报 | 2026年07月01日10Trae国际版与国内版深度测评：AI原生IDE的双生花