从零搭建 macOS Flutter 开发环境指南

一、基础环境配置

1. 安装 Flutter SDK

# 下载最新稳定版
git clone https://github.com/flutter/flutter.git -b stable

# 添加环境变量（添加到 ~/.zshrc 或 ~/.bash_profile）
export PATH="$PATH:`pwd`/flutter/bin"

# 验证安装
flutter doctor

1. 安装 Xcode

• 通过 App Store 安装最新版 Xcode
• 完成后执行：

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

二、Xcode 关键配置

1. 开启开发者模式

sudo DevToolsSecurity -enable

1. 证书配置

• 打开 Xcode → Preferences → Accounts
• 添加 Apple ID → 选择团队
• 自动管理签名（Automatically manage signing）

1. 项目设置

# 首次创建项目时执行
flutter create my_app
cd my_app
open ios/Runner.xcworkspace

• 在 Xcode 中：Runner → Signing & Capabilities
• 确保 Team 已选择
• Bundle Identifier 格式：com.yourdomain.appname

三、模拟器调试

1. 创建模拟器

• 打开 Xcode → Window → Devices and Simulators
• 点击 ➕ 添加新模拟器（建议选择 iPhone 14/iOS 16）

1. 启动调试

# 查看可用模拟器列表
flutter emulators

# 启动模拟器
flutter emulators --launch apple_ios_simulator

# 运行应用
flutter run

1. 调试技巧

• 快捷键 r：热重载
• 快捷键 p：显示网格布局
• 快捷键 o：切换平台渲染模式

四、热重载问题修复方案

问题现象	解决方案	终端指令
修改后无反应	重置构建缓存	flutter clean
报错Lost connection	重启模拟器	flutter emulators --launch apple_ios_simulator
UI状态不更新	强制完全重启	flutter run --purge-persistent-callback-cache
插件未同步	重新获取依赖	flutter pub get
Xcode编译错误	更新CocoaPods	cd ios && pod install --repo-update

五、环境验证

执行完整检查：

flutter doctor

正常输出应包含：

[✓] Flutter (Channel stable...)
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] VS Code / Android Studio (可选)
[✓] Connected device (1 available)

最佳实践：开发时保持终端运行 flutter run --verbose 可实时查看详细日志，定位90%以上的热重载失败原因。建议搭配 VS Code 的 Flutter 插件实现保存自动热重载（需开启 dart.saveTrigger 配置项）。