flutter-cn-setup

---

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 达到可日常开发状态

快速诊断

1. 确认系统与芯片架构： - uname -m（期望 arm64 或 x86_64） - sw_vers 2. 检查 Homebrew 是否存在： - brew --version 3. 检查当前 Flutter 状态： - which flutter - flutter --version - flutter doctor -v 4. 若已安装 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/flutter

3) 配置 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

1. 安装 Android Studio（图形界面安装即可）。 2. 打开 Android Studio 一次，完成首次 SDK 初始化。 3. 确认已安装以下 SDK 组件： - Android SDK Platform (latest stable API) - Android SDK Platform-Tools - Android SDK Command-line Tools - Android Emulator 4. 接受 licenses：

flutter doctor --android-licenses

若提示缺少 sdkmanager，在 SDK Manager 补装 command-line tools 后重试。

6) iOS toolchain（按需）

1. 从 App Store 安装 Xcode。 2. 执行：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

3. 安装 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

重新执行：

- 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

验收闭环

排障时建议按以下循环执行：

1. 运行 bootstrap 脚本： - bash scripts/bootstrap-flutter-cn.sh 2. 运行 validator： - bash scripts/validate-flutter-cn.sh 3. 如果 validator 失败： - 先修复优先级最高的 FAIL 项 - 再次运行 validator 4. 仅当结果为 READY for development 时结束

技能输出格式

执行本 Skill 后给用户的回复应包含：

1. 当前状态：已安装与缺失项 2. 已执行命令：按阶段归类 3. 阻塞问题：精确报错与可能原因 4. 下一步动作：最小可执行解阻命令 5. 最终验收：对 flutter doctor -v 的简明结论

约束

不要默认要求 iOS；先确认用户是否仅需 Android。

默认使用 stable channel，除非用户明确要求 beta/master。

不要粗暴覆盖 shell profile；优先幂等追加。

不要默认卸载现有 SDK，除非用户明确要求清理。

附加资料

错误到修复速查：troubleshooting.md

分场景回复模板：examples.md

Skill 回归检查清单：self-test.md