目录
[📋 最终状态](#📋 最终状态)
[🔴 失败情况记录](#🔴 失败情况记录)
[失败 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 官方行为）。