环境说明
测试环境：
操作系统：macOS 15.7.2 (支持 macOS 10.14+)
芯片架构：Apple Silicon (M1/M2/M3/M4)
Flutter 版本：3.35.7 (stable)
支持的开发平台：
iOS 应用开发
macOS 应用开发
Android 应用开发
Web 应用开发
安装 Dart
方法一：通过 Homebrew 安装（推荐）
# 1. 安装 Homebrew（如已安装可跳过）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 2. 安装 Dart
brew tap dart-lang/dart
brew install dart
# 3. 验证安装
dart --version
方法二：通过 Flutter 安装
如果计划使用 Flutter，可以跳过单独安装 Dart，因为 Flutter SDK 已包含 Dart。
安装 Flutter
配置国内镜像（中国大陆用户必须）
在安装 Flutter 之前，先配置国内镜像以避免网络问题：
# 编辑配置文件
nano ~/.zshrc # macOS Catalina+ 默认使用 zsh
# 或
nano ~/.bash_profile # 较旧的 macOS 使用 bash
# 添加以下内容到文件末尾
export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter
# 保存文件（Ctrl+O, Enter, Ctrl+X）
# 使配置生效
source ~/.zshrc # 或 source ~/.bash_profile
方法一：使用 Homebrew 安装
brew install --cask flutter
⚠️ 可能遇到的问题：
如果出现 curl: (35) Recv failure: Connection reset by peer 错误，说明网络无法访问 Google 服务器，请使用方法二。
方法二：从国内镜像手动安装（推荐）
# 1. 创建开发目录
mkdir -p ~/development
cd ~/development
# 2. 从清华镜像克隆 Flutter
git clone https://mirrors.tuna.tsinghua.edu.cn/git/flutter-sdk.git flutter -b stable
# 3. 添加 Flutter 到 PATH
nano ~/.zshrc
# 添加以下内容到文件末尾
export PATH="$PATH:$HOME/development/flutter/bin"
# 保存并使配置生效
source ~/.zshrc
# 4. 验证安装
flutter --version
运行 Flutter Doctor
flutter doctor
此命令会检查开发环境配置情况，接下来根据检查结果配置各平台环境。
配置 iOS/macOS 开发环境
1. 安装 Rosetta（Apple Silicon Mac 必须）
sudo softwareupdate --install-rosetta --agree-to-license
2. 安装 Xcode
方式一：通过 App Store 安装（推荐）
打开 App Store
搜索 "Xcode"
点击"获取"并等待下载完成（约 10-15 GB）
方式二：通过开发者网站下载
访问：https://developer.apple.com/xcode/
3. 配置 Xcode
# 设置 Xcode 命令行工具路径
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
# 运行首次配置
sudo xcodebuild -runFirstLaunch
# 同意许可协议
sudo xcodebuild -license accept
4. 升级 Ruby（必须）
macOS 自带的 Ruby 版本过旧（2.6.x），需要升级到 3.1+：
# 1. 通过 Homebrew 安装最新 Ruby
brew install ruby
# 2. 配置 Ruby PATH
nano ~/.zshrc
# 添加以下内容（注意版本号可能不同）
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
export PATH="/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"
# 保存并使配置生效
source ~/.zshrc
# 3. 验证 Ruby 版本（应显示 3.x）
ruby -v
5. 安装 CocoaPods
# 安装 CocoaPods
sudo gem install cocoapods
# 验证安装
pod --version
⚠️ 如果 pod 命令找不到：
# 查看 gem 可执行文件目录
gem environment | grep "EXECUTABLE DIRECTORY"
# 假设输出是 /opt/homebrew/lib/ruby/gems/3.4.0/bin
# 添加到 PATH
echo 'export PATH="/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 再次验证
pod --version
6. 测试 iOS 开发环境
# 打开 iOS 模拟器
open -a Simulator
# 创建测试项目
flutter create test_app
cd test_app
# 在模拟器中运行
flutter run
配置 Android 开发环境
1. 安装 Android Studio
访问：https://developer.android.com/studio
下载 Mac 版本（约 1 GB）
打开下载的
.dmg文件将 Android Studio 拖入应用程序文件夹
2. 首次启动配置
启动 Android Studio
选择 "Standard" 安装类型
等待 SDK、工具和模拟器下载完成（约 3-5 GB）
3. 安装 Android SDK 命令行工具
在 Android Studio 中：
打开
Settings/Preferences→Appearance & Behavior→System Settings→Android SDK选择
SDK Tools标签勾选：
Android SDK Command-line Tools
Android SDK Platform-Tools
Android SDK Build-Tools
点击
Apply并等待下载完成
4. 配置环境变量
# 编辑配置文件
nano ~/.zshrc
# 添加以下内容（路径可能需要根据实际情况调整）
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
# 保存并使配置生效
source ~/.zshrc
5. 接受 Android 许可协议
flutter doctor --android-licenses
按 y 接受所有许可协议。
6. 创建 Android 虚拟设备
在 Android Studio 中：
点击
Tools→Device Manager点击
Create Device选择设备类型（如 Pixel 7）
选择系统镜像（推荐最新版本）
点击
Finish
7. 测试 Android 开发环境
# 启动虚拟设备（在 Android Studio Device Manager 中启动）
# 在虚拟设备中运行应用
cd test_app
flutter run
配置 Web 开发环境
Web 开发环境最简单，只需要安装 Chrome 浏览器即可。
1. 安装 Chrome（如未安装）
访问：https://www.google.com/chrome/
2. 启用 Web 支持
flutter config --enable-web
3. 测试 Web 开发环境
cd test_app
# 在 Chrome 中运行
flutter run -d chrome
常见问题与解决方案
问题 1：Homebrew 安装 Flutter 失败，提示网络错误
错误信息：
curl: (35) Recv failure: Connection reset by peer
Error: Download failed on Cask 'flutter'
解决方案： 使用手动安装方式，从国内镜像克隆 Flutter。参见 方法二：从国内镜像手动安装
问题 2：CocoaPods 安装失败，提示 Ruby 版本过低
错误信息：
securerandom requires Ruby version >= 3.1.0. The current ruby version is 2.6.10.210.
解决方案： 升级 Ruby 到 3.1+ 版本。参见 4. 升级 Ruby（必须）
问题 3：pod 命令找不到
错误信息：
zsh: command not found: pod
解决方案：
# 1. 查找 gem 可执行文件目录
gem environment | grep "EXECUTABLE DIRECTORY"
# 2. 将输出的目录添加到 PATH
echo 'export PATH="输出的目录:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 3. 验证
pod --version
问题 4：Flutter 下载依赖很慢
解决方案： 确保已配置国内镜像源。参见 配置国内镜像
问题 5：Apple Silicon Mac 运行 Flutter 提示 Rosetta 错误
错误信息：
Downloaded executables cannot execute on host.
Flutter requires the Rosetta translation environment on ARM Macs.
解决方案：
sudo softwareupdate --install-rosetta --agree-to-license
问题 6：Android SDK 路径未找到
解决方案：
# 手动设置 Android SDK 路径
flutter config --android-sdk $HOME/Library/Android/sdk
验证安装
运行完整检查
flutter doctor -v
理想的输出结果
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.35.7, on macOS 15.7.2, locale zh-Hans-CN)
[✓] Android toolchain - develop for Android devices
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Android Studio
[✓] VS Code
[✓] Connected device
[✓] Network resources
• No issues found!
创建并运行测试项目
# 创建新项目
flutter create hello_flutter
cd hello_flutter
# 在不同平台运行
flutter run -d chrome # Web
flutter run -d "iPhone 15 Pro" # iOS 模拟器
flutter run -d macos # macOS 应用
flutter run -d emulator-5554 # Android 模拟器
推荐开发工具
VS Code 扩展
Flutter - 官方 Flutter 支持
Dart - Dart 语言支持
Flutter Widget Snippets - Flutter 代码片段
安装方式：
打开 VS Code
点击扩展图标（Cmd+Shift+X）
搜索并安装上述扩展
Android Studio 插件
Flutter - 官方 Flutter 插件
Dart - Dart 语言支持
安装方式：
打开 Android Studio
Preferences→Plugins搜索并安装上述插件
下一步
官方文档：https://flutter.dev/docs
中文文档：https://flutter.cn/docs
示例代码：https://flutter.dev/docs/cookbook
官方教程：https://flutter.dev/docs/get-started/codelab
版本信息
文档版本：1.0
更新日期：2025-11-07
Flutter 版本：3.35.7 (stable)
测试环境：macOS 15.7.2 (Apple Silicon)