Flutter CN 环境安装

快速开始

大多数场景直接执行：

bash
cd .cursor/skills/flutter-cn-setup
bash scripts/bootstrap-flutter-cn.sh
bash scripts/validate-flutter-cn.sh

仅 Android 快速路径：

bash
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. 1. 确认系统与芯片架构：

- uname -m（期望 arm64 或 x86_64） - sw_vers

1. 2. 检查 Homebrew 是否存在：

- brew --version

1. 3. 检查当前 Flutter 状态：

- which flutter - flutter --version - flutter doctor -v

1. 4. 若已安装 Flutter，优先 修复/升级，除非用户明确要求全量重装。

中国区镜像配置

下载依赖前先配置：

bash
export PUBHOSTEDURL=https://pub.flutter-io.cn
export FLUTTERSTORAGEBASE_URL=https://storage.flutter-io.cn

持久化到 shell 配置（zsh 默认 ~/.zshrc）：

bash
cat <> ~/.zshrc

Flutter 中国区镜像

export PUBHOSTEDURL=https://pub.flutter-io.cn
export FLUTTERSTORAGEBASE_URL=https://storage.flutter-io.cn
EOF
source ~/.zshrc

如果镜像不稳定，先和用户确认替代方案再切换 URL。

安装流程（macOS）

可复制以下清单跟踪进度：

text
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：

bash
brew install git curl unzip xz

如果缺少 Homebrew，先安装后重试。

2) 安装 Flutter SDK

推荐目录：

• - Apple Silicon：~/development/flutter
• Intel：~/development/flutter

建议使用 git 安装（便于后续升级）：

bash
mkdir -p ~/development
git clone https://github.com/flutter/flutter.git -b stable ~/development/flutter

3) 配置 PATH 与镜像

添加 Flutter 可执行路径：

bash
cat <> ~/.zshrc

Flutter SDK 路径

export PATH=$PATH:$HOME/development/flutter/bin
EOF
source ~/.zshrc

确认 ~/.zshrc 中也已写入镜像变量（见上文镜像配置）。

4) 执行 precache 与 doctor

bash
flutter --version
flutter precache
flutter doctor -v

若提示命令不存在，重新打开终端或再次 source shell profile 后重试。

5) Android toolchain

1. 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

1. 4. 接受 licenses：

bash
flutter doctor --android-licenses

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

6) iOS toolchain（按需）

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

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

1. 3. 安装 CocoaPods：

bash
brew install cocoapods
pod --version

若 CocoaPods 因网络或权限失败，优先使用 Homebrew 路径，不要先切 Ruby gem 方案。

7) 设备与模拟器就绪检查

bash
flutter devices

期望结果：

• - Android 开发至少有一个 emulator 或真机
• iOS 开发可识别 simulator（open -a Simulator）

8) 端到端验证

bash
flutter create hellofluttercn
cd hellofluttercn
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
bash scripts/bootstrap-flutter-cn.sh

可选环境变量：

bash
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 后续人工步骤
• 创建冒烟工程 ~/hellofluttercn

执行验收：

bash
bash scripts/validate-flutter-cn.sh

验收参数：

bash

仅 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. 1. 运行 bootstrap 脚本：

- bash scripts/bootstrap-flutter-cn.sh

1. 2. 运行 validator：

- bash scripts/validate-flutter-cn.sh

1. 3. 如果 validator 失败：

- 先修复优先级最高的 FAIL 项 - 再次运行 validator

1. 4. 仅当结果为 READY for development 时结束

技能输出格式

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

1. 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