- name
- flutter-cn-setup
- description
- 为中国区开发者在新电脑上搭建完整 Flutter 开发环境，覆盖 Android/iOS toolchain、镜像配置、诊断和验收。用户提到安装 Flutter、中国区镜像、修复 flutter doctor、或新 macOS 初始化 Flutter 环境时使用。
Flutter CN 环境安装
快速开始
大多数场景直接执行：
cd .cursor/skills/flutter-cn-setup
bash scripts/bootstrap-flutter-cn.sh
bash scripts/validate-flutter-cn.sh仅 Android 快速路径：
cd .cursor/skills/flutter-cn-setup
NEED_IOS=no bash scripts/bootstrap-flutter-cn.sh
NEED_IOS=no bash scripts/validate-flutter-cn.sh适用范围
本 Skill 用于在中国区网络下，为 全新 macOS 设备搭建完整 Flutter 环境。
目标结果：
- Flutter SDK 已安装并加入
PATH - Flutter 与 Dart 包下载镜像已配置
- Android toolchain 可用（Android Studio + SDK + licenses）
- iOS toolchain 可用（Xcode + CocoaPods，按需）
flutter doctor达到可日常开发状态
快速诊断
- 确认系统与芯片架构：
- uname -m（期望 arm64 或 x86_64） - sw_vers
- 检查 Homebrew 是否存在：
- brew --version
- 检查当前 Flutter 状态：
- which flutter - flutter --version - flutter doctor -v
- 若已安装 Flutter，优先 修复/升级，除非用户明确要求全量重装。
中国区镜像配置
下载依赖前先配置：
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn持久化到 shell 配置（zsh 默认 ~/.zshrc）：
cat <<'EOF' >> ~/.zshrc
# Flutter 中国区镜像
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
EOF
source ~/.zshrc如果镜像不稳定，先和用户确认替代方案再切换 URL。
安装流程（macOS）
可复制以下清单跟踪进度：
Flutter CN 安装进度
- [ ] 1) 安装基础工具（git、curl、unzip、xz）
- [ ] 2) 安装 Flutter SDK
- [ ] 3) 配置 PATH 与镜像
- [ ] 4) 执行 flutter precache 与 doctor
- [ ] 5) 安装 Android Studio + Android SDK + licenses
- [ ] 6) 安装 Xcode + CocoaPods（如需 iOS）
- [ ] 7) 验证 Android emulator / iOS simulator
- [ ] 8) 创建并运行示例应用1) 基础工具
优先使用 Homebrew：
brew install git curl unzip xz如果缺少 Homebrew，先安装后重试。
2) 安装 Flutter SDK
推荐目录：
- Apple Silicon：
~/development/flutter - Intel：
~/development/flutter
建议使用 git 安装（便于后续升级）：
mkdir -p ~/development
git clone https://github.com/flutter/flutter.git -b stable ~/development/flutter3) 配置 PATH 与镜像
添加 Flutter 可执行路径：
cat <<'EOF' >> ~/.zshrc
# Flutter SDK 路径
export PATH="$PATH:$HOME/development/flutter/bin"
EOF
source ~/.zshrc确认 ~/.zshrc 中也已写入镜像变量（见上文镜像配置）。
4) 执行 precache 与 doctor
flutter --version
flutter precache
flutter doctor -v若提示命令不存在，重新打开终端或再次 source shell profile 后重试。
5) Android toolchain
- 安装 Android Studio（图形界面安装即可）。
- 打开 Android Studio 一次，完成首次 SDK 初始化。
- 确认已安装以下 SDK 组件：
- Android SDK Platform (latest stable API) - Android SDK Platform-Tools - Android SDK Command-line Tools - Android Emulator
- 接受 licenses：
flutter doctor --android-licenses若提示缺少 sdkmanager，在 SDK Manager 补装 command-line tools 后重试。
6) iOS toolchain（按需）
- 从 App Store 安装 Xcode。
- 执行：
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch- 安装 CocoaPods：
brew install cocoapods
pod --version若 CocoaPods 因网络或权限失败，优先使用 Homebrew 路径，不要先切 Ruby gem 方案。
7) 设备与模拟器就绪检查
flutter devices期望结果：
- Android 开发至少有一个 emulator 或真机
- iOS 开发可识别 simulator（
open -a Simulator）
8) 端到端验证
flutter create hello_flutter_cn
cd hello_flutter_cn
flutter pub get
flutter run若 pub 下载慢或失败，重新检查当前 shell 会话与 shell profile 中的镜像变量。
常见问题处理
flutter doctor 提示 Android toolchain 缺失
- 确保 Android Studio 至少打开并初始化过一次。
- 检查 Flutter 的 Android SDK 配置：
- flutter config --android-sdk <sdk-path>
- 重新执行：
- flutter doctor -v - flutter doctor --android-licenses
Unable to find git in your PATH
- 安装 git（
brew install git） - 重启终端
- 验证
git --version
CocoaPods repo/spec timeout
- 先确认基础网络与镜像配置。
- 重试
pod --version与 iOS 构建。 - 仍失败时，先记录完整报错，再与用户确定 mirror/proxy 策略。
Xcode license 或首次启动未完成
- 执行：
- sudo xcodebuild -license accept - sudo xcodebuild -runFirstLaunch
工具脚本
使用内置脚本执行可重复安装：
bash scripts/bootstrap-flutter-cn.sh可选环境变量：
NEED_IOS=no \
FLUTTER_DIR="$HOME/development/flutter" \
SHELL_PROFILE="$HOME/.zshrc" \
bash scripts/bootstrap-flutter-cn.sh脚本行为：
- 通过 Homebrew 安装基础工具
- 通过 git 安装或更新 Flutter
stable - 以幂等方式写入镜像和 PATH
- 执行
flutter precache与flutter doctor -v - 输出 Android/iOS 后续人工步骤
- 创建冒烟工程
~/hello_flutter_cn
执行验收：
bash scripts/validate-flutter-cn.sh验收参数：
# 仅 Android
NEED_IOS=no bash scripts/validate-flutter-cn.sh
# 仅 iOS
NEED_ANDROID=no bash scripts/validate-flutter-cn.sh验收输出：
- 每项检查输出 PASS/WARN/FAIL
- 最终结果：
READY for development或NOT READY - 退出码：ready 为
0，not ready 为1
验收闭环
排障时建议按以下循环执行：
- 运行 bootstrap 脚本：
- bash scripts/bootstrap-flutter-cn.sh
- 运行 validator：
- bash scripts/validate-flutter-cn.sh
- 如果 validator 失败：
- 先修复优先级最高的 FAIL 项 - 再次运行 validator
- 仅当结果为
READY for development时结束
技能输出格式
执行本 Skill 后给用户的回复应包含：
- 当前状态：已安装与缺失项
- 已执行命令：按阶段归类
- 阻塞问题：精确报错与可能原因
- 下一步动作：最小可执行解阻命令
- 最终验收：对
flutter doctor -v的简明结论
约束
- 不要默认要求 iOS；先确认用户是否仅需 Android。
- 默认使用 stable channel，除非用户明确要求 beta/master。
- 不要粗暴覆盖 shell profile；优先幂等追加。
- 不要默认卸载现有 SDK，除非用户明确要求清理。
附加资料
- 错误到修复速查：
[troubleshooting.md](troubleshooting.md) - 分场景回复模板：
[examples.md](examples.md) - Skill 回归检查清单：
[self-test.md](self-test.md)