在 macOS 上搭建完整的 Flutter 开发环境（支持 Android / Web / 原生 macOS）

以下指南假设你更倾向于命令行 + VS Code 为主的开发方式。流程分为：

  1. 安装 Flutter SDK
  2. 配置 Android 环境
  3. 配置 macOS (桌面/插件) + Web 支持
  4. VS Code 集成与常用插件
  5. 创建 + 运行第一个跨平台 App
  6. 针对你 flutter doctor 输出的诊断 & 修复建议

一、安装 Flutter SDK（推荐通过 Homebrew）

使用 Homebrew 来安装 Flutter 可以简化路径管理与后续升级。

# （如果尚未安装 Homebrew）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Flutter（使用 cask 方式获得完整 Flutter 包括 dart 等工具）
brew install --cask flutter

安装完成后，重启终端（或执行 source ~/.zshrc / source ~/.zsh_profile 等）以让 shell 拿到最新 PATH。然后运行：

flutter doctor

这步会检查当前环境中缺失的组件，并给出提示。

二、配置 Android 环境（即使你主要使用物理设备）

即便你最终是用物理设备调试，Flutter 仍需 Android SDK、平台工具 (platform-tools)、命令行工具等，这些通常由 Android Studio 提供。但如果你不想安装完整 IDE，也可以单独安装这些组件。

方式 A：安装 Android Studio（推荐）

  1. 前往 [Android Studio 官网] 下载 macOS 版本，安装到 Applications 文件夹。

  2. 第一次打开时，启动设置向导，选择 “Standard” 安装以获取 SDK、命令行工具、模拟器等。

  3. 在 Android Studio 内部打开 AVD 管理器，创建一个虚拟设备（例如 Pixel 系列），选择合适的系统镜像，并启动模拟器。VS Code / Flutter 会自动识别运行中的 Emulator。

  4. 接受 Android 相关许可协议：

    flutter doctor --android-licenses

    在提示中输入 y 接受。

方式 B：仅安装 SDK / 命令行工具（不装完整 IDE）

如果你不希望安装 Android Studio，可以手动安装 Android SDK 的命令行、platform-tools 等：

  1. 下载 Android SDK Command-line Tools（从 Android 开发者官网）。

  2. 解压并放到某个固定路径，比如 ~/development/android-sdk。

  3. 安装 platform-tools、build-tools、platforms 等组件（通过 sdkmanager 工具）。

  4. 在 shell 的配置文件（如 ~/.zshrc）中添加：

    export ANDROID_SDK_ROOT="$HOME/development/android-sdk"
export PATH="$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$PATH"

  5. 重启终端后，运行：

    flutter config --android-sdk $ANDROID_SDK_ROOT
flutter doctor
flutter doctor --android-licenses

  6. 此时 flutter devices 若连接有物理设备并成功授权，则应能看到设备。

使用物理 Android 设备调试

  1. 在手机上启用开发者模式 & USB 调试（Settings → About phone → 连续点击 build number → 再返回到 Developer options 打开 USB 调试）。

  2. 用 USB 数据线连接手机，确认手机侧弹出 “信任此设备 / 允许 USB 调试” 对话框，点击允许。

  3. 在终端中运行：

    flutter devices

    应该能看到你的设备（如 “Samsung S23 (device)” 等）。

  4. 在 VS Code 的设备列表里选择这个物理设备，然后按 F5 启动调试 / 运行。

三、配置 macOS & Web（桌面 / 浏览器 支持）

macOS（原生桌面支持）

Flutter 的 macOS 支持要求你安装 Xcode + CocoaPods（用于管理含本地插件的依赖）。官方文档有详尽说明。(docs.flutter.dev)

步骤：

  1. 如果尚未安装 Xcode，从 App Store 或 Apple Developer 下载并安装最新版本。

  2. 在终端执行：

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

    这两行会设置命令行工具指向 Xcode 以及触发首次启动任务（如构建许可、组件安装等）。(docs.flutter.dev)

  3. 如果尚未接受 Xcode 许可协议：

    sudo xcodebuild -license

    阅读并接受条款。(docs.flutter.dev)

  4. 安装 CocoaPods：

    brew install cocoapods

    或者通过 Ruby gem 安装（根据你的 Ruby 版本选择合适方式）。(docs.flutter.dev)

    注意：在 macOS Sonoma / Xcode 15 等版本上，CocoaPods 有时不被正确识别，即便已安装。你可能要确认 Ruby 环境、gem 路径是否在 PATH 中。(GitHub)

  5. 启用 macOS 构建目标：

    flutter config --enable-macos-desktop

  6. 运行 flutter doctor，检查 macOS 部分是否无错误。(docs.flutter.dev)

Web 支持

Flutter 默认支持 Web 平台（通常以 Chrome 浏览器为承载），你只需启用 Web 支持：

flutter config --enable-web

确保系统上装有 Google Chrome（作为 Flutter Web 的默认浏览器）。
运行 flutter doctor，你应能看到 Chrome 支持被识别为正常项。

四、VS Code 集成 + 推荐插件

使用 VS Code 作为你主要开发界面，配合 Flutter / Dart 扩展，可获得很好的体验。

  1. 在 VS Code 中打开扩展面板（Cmd + Shift + X）。

  2. 搜索 “Flutter”，安装由 Dart Code 出品的扩展（安装 Flutter 扩展时，会自动包含 Dart 扩展）。

  3. 常用功能／快捷命令（通过 Cmd + Shift + P 打开命令面板）：

    • Flutter: New Project：创建新项目
    • Flutter: Run Flutter Doctor：在 VS Code 里检查环境
    • Flutter: Hot Reload、Hot Restart
    • Flutter: Open DevTools 等

  4. 在状态栏右下角可选择当前设备／模拟器／浏览器／macOS 目标，点击后切换目标。

  5. 推荐插件（根据个人习惯，可选安装）：

    • Pubspec Assist：直接在 pubspec.yaml 中搜索、添加依赖
    • Awesome Flutter Snippets：提供大量 Flutter 小片段（Widgets、常用语法）
    • Better Comments：增强注释的可读性（分类警告、问题、TODO 等）

五、创建 & 运行第一个跨平台 App

以下为标准流程：

  1. 在终端 / VS Code 中创建项目：

    flutter create my_app
cd my_app

    或者在 VS Code 中通过 Flutter: New Project。

  2. 打开项目（例如在终端使用 code .，或在 VS Code 里选择打开）。

  3. 启动一个设备／模拟器／浏览器／macOS 目标（取决于你希望运行的平台）。

  4. 在 VS Code 中按 F5（或 Run → Debug），启动调试 / 运行。

  5. 你可以在运行时使用 Hot Reload / Hot Restart 快速刷新 UI 改动。

你可以随时通过设备列表切换目标：

  • Android → 模拟器或物理设备
  • macOS → 原生桌面
  • Web → Chrome 浏览器

最后，在项目目录里运行一次：

flutter doctor

期待看到所有平台 / 工具栏目的绿色 ✅ 表示环境配置正确。

六、执行 flutter doctor 的输出分析 + 修复建议

如果 flutter doctor 结果如下（我摘要关键部分）：

[✓] Flutter (Channel stable, 3.35.4, on macOS 26.0 …)
[✗] Android toolchain – Unable to locate Android SDK.
[✗] Xcode – installation incomplete; CocoaPods not installed.
[✓] Chrome – develop for the web
[!] Android Studio (not installed)
[✓] VS Code
[✓] Connected device (2 available)

也就是说，当前 Flutter 本身安装正常，但有三大缺陷：

  1. Android SDK 未找到
  2. Xcode 配置不完整 + CocoaPods 缺失
  3. Android Studio 未安装

下面是修复建议：

1. 解决 “Unable to locate Android SDK”

  • 最简单：安装 Android Studio。启动后，它会帮你安装 SDK、命令行工具、平台工具等。

  • 如果你已手动安装 Android SDK，则执行：

    flutter config --android-sdk /path/to/your/android/sdk

    其中 /path/to/your/android/sdk 为你 SDK 的根目录。然后再运行 flutter doctor。

  • 然后执行：

    flutter doctor --android-licenses

    接受所有提示。

确认 flutter doctor 的 Android toolchain 项目不再报错。

2. 修复 Xcode + CocoaPods 问题

  • 安装完整 Xcode（如果尚未安装）。从 App Store 或 Apple Developer 下载。

  • 执行：

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

    这几步确保命令行工具选对且你已接受许可协议。(docs.flutter.dev)

  • 安装 CocoaPods：

    brew install cocoapods

    或者（在某些环境中）使用 gem：

    sudo gem install cocoapods

    但请注意：在 macOS 最新版本（如 Sonoma / Xcode 15）里，系统自带 Ruby 有可能权限受限或与系统更新冲突，这时候使用 Homebrew 提供的 Ruby + gem 安装可能更可靠。(GitHub)

  • 安装 CocoaPods 之后，如果 flutter doctor 仍然提示 “CocoaPods not installed”，你可能要检查 gem 安装路径是否在你的 PATH 中（比如 ~/.gem/bin 或 Homebrew Ruby 的 gem 路径）。(GitHub)

  • 最后，再执行 flutter doctor 检查是否已修正。

3. 考虑是否安装 Android Studio

虽然你可以选择不装 Android Studio，但很多开发者还是安装它以便管理 SDK、AVD 模拟器、插件管理等。如果你最终决定安装：

  • 下载 Android Studio 并安装
  • 打开它运行一次设置向导以配置 SDK
  • 确保 Flutter / Dart 插件已安装在 Android Studio 中

安装后，flutter doctor 应该识别 Android Studio 并给出绿色勾。

总结 & 提醒

  • 使用 Homebrew 安装 Flutter 是一种简洁、易维护的方式。
  • 即使你偏好物理设备调试，也必须有 Android SDK、platform-tools、命令行工具等。
  • 当你看到 flutter doctor 报错，通常它已经明确指出缺失的组件。
  • CocoaPods 在 macOS / iOS / macOS 桌面插件中非常关键，需要正确安装并被 Flutter 检测到。
  • 在 macOS 最新版本 + Xcode 版本中，有时 CocoaPods 虽已安装但仍被 flutter doctor 视为“未安装” — 此时要检查 Ruby / gem 路径设置是否正确。