Flutter 开发环境搭建：从零到第一次运行

写在前面

很多人学 Flutter 卡在第一步------环境搭建。

不是代码难，是坑太多：SDK 解压到哪里、环境变量怎么配、模拟器跑不起来、flutter doctor 报了一堆错不知道从哪里下手。

这篇文章把整个流程走一遍，每个常见坑都标出来，按步骤做下去，最终目标是在你的电脑上成功运行第一个 Flutter 应用。

一、Flutter SDK 安装与配置

1.1 下载 SDK

打开 Flutter 官网：flutter.dev

点击「Get started」，选择你的操作系统（macOS / Windows / Linux），下载对应的 SDK 压缩包。

⚠️ 注意：不要从 GitHub 直接克隆，官网下载的是稳定版，更适合入门。

文件大小大约在 1-2 GB，国内下载可能较慢，可以用镜像站：

bash 复制代码

# 国内镜像（中国大陆用户）
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
export PUB_HOSTED_URL="https://pub.flutter-io.cn"

把这两行加入你的 shell 配置文件（~/.zshrc 或 ~/.bashrc），后续 pub 依赖下载也会走国内镜像，速度快很多。

1.2 解压并放置到合适的位置

macOS / Linux：

bash 复制代码

# 解压到 home 目录下的 development 文件夹
mkdir -p ~/development
cd ~/development
unzip ~/Downloads/flutter_macos_xxx.zip

Windows：

建议解压到 C:\development\flutter，不要放在以下路径：

桌面（路径含空格容易出问题）
C:\Program Files（需要管理员权限，后续会有麻烦）
任何路径中包含中文字符的文件夹

⚠️ 这是 Windows 上最常见的坑：路径含有空格或中文，后续命令会报莫名其妙的错误。

1.3 配置环境变量

这一步是重点，也是出错最多的地方。

macOS（以 zsh 为例）：

bash 复制代码

# 打开配置文件
nano ~/.zshrc

# 在文件末尾添加
export PATH="$PATH:$HOME/development/flutter/bin"

# 保存后执行让配置生效
source ~/.zshrc

Windows：

搜索「编辑系统环境变量」
点击「环境变量」
在「用户变量」的 Path 里，点「新建」
添加 Flutter 的 bin 目录路径，例如 C:\development\flutter\bin
确定，重启终端

验证配置是否生效：

bash 复制代码

flutter --version

如果输出了版本号，说明环境变量配置成功。如果提示「command not found」，检查路径是否正确，以及是否重启了终端。

二、安装 IDE

2.1 Android Studio（推荐）

Flutter 官方推荐使用 Android Studio，原因是它内置了 Android SDK 管理器和模拟器，配置最省事。

下载地址：developer.android.com/studio

安装完成后，打开 Android Studio，进入 Preferences → Plugins（macOS）或 File → Settings → Plugins（Windows），搜索安装两个插件：

Flutter（必装）
Dart（必装，Flutter 插件通常会自动安装）

安装完成后重启 Android Studio。

2.2 VS Code（轻量选择）

如果更习惯 VS Code，也完全可以用于 Flutter 开发。

打开 VS Code，按 Ctrl+Shift+X（Windows）或 Cmd+Shift+X（macOS）打开扩展面板，搜索安装：

Flutter（会自动安装 Dart 扩展）

VS Code 的优势是启动快、占用内存少；Android Studio 的优势是 Android 相关工具链集成更完整。

推荐策略： 初学阶段用 Android Studio，熟悉之后可以换 VS Code 提升速度。

三、配置 Android 模拟器

3.1 安装 Android SDK

打开 Android Studio，进入 SDK Manager：

macOS：Android Studio → Preferences → Appearance & Behavior → System Settings → Android SDK
Windows：File → Settings → Appearance & Behavior → System Settings → Android SDK

确认安装了以下内容：

Android SDK Platform（建议安装最新稳定版，如 Android 14）
Android SDK Build-Tools
Android Emulator
Android SDK Platform-Tools

3.2 创建模拟器

在 Android Studio 顶部工具栏找到「Device Manager」（或从菜单 Tools → Device Manager 打开）。

点击「Create Device」，选择设备型号：

入门推荐：Pixel 6 或 Pixel 7（尺寸适中，性能好）
选择系统镜像：推荐选带 Google APIs 的版本，支持 Google 服务

点击 Next，选一个系统镜像，等待下载完成（第一次下载比较慢），然后 Finish。

3.3 启动模拟器

在 Device Manager 中点击播放按钮启动模拟器。

⚠️ 常见问题：模拟器启动失败或特别卡

Windows 用户： 需要开启 Hyper-V 或 HAXM 硬件加速。进入 BIOS 开启虚拟化技术（Intel VT-x / AMD-V），然后在 SDK Manager 的 SDK Tools 标签页安装「Intel x86 Emulator Accelerator (HAXM installer)」。

macOS M 系列芯片用户： 选择系统镜像时选「arm64」版本，不要选 x86，否则模拟器会非常慢。

四、配置 iOS 模拟器（仅 macOS）

4.1 安装 Xcode

打开 Mac App Store，搜索「Xcode」，安装。

Xcode 体积很大（约 15 GB），需要耐心等待。

安装完成后，打开终端执行：

bash 复制代码

# 同意 Xcode 许可协议（必须做，否则后续步骤会报错）
sudo xcodebuild -license accept

# 安装 Xcode 命令行工具
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

4.2 启动 iOS 模拟器

bash 复制代码

# 从命令行打开模拟器
open -a Simulator

或者在 Xcode 中：Xcode → Open Developer Tool → Simulator

模拟器启动后，可以通过 Hardware → Device 菜单切换不同的 iPhone 型号。

4.3 安装 CocoaPods

Flutter 的 iOS 插件依赖 CocoaPods 管理，需要安装：

bash 复制代码

sudo gem install cocoapods

⚠️ 如果遇到权限问题或版本冲突，推荐用 Homebrew 安装：
bash 复制代码
brew install cocoapods

五、真机调试配置

5.1 Android 真机调试

第一步：开启开发者选项

手机设置 → 关于手机 → 连续点击「版本号」7 次，出现「您已进入开发者模式」提示。

第二步：开启 USB 调试

设置 → 开发者选项 → 打开「USB 调试」开关。

第三步：连接电脑

用 USB 数据线连接手机和电脑，手机上会弹出「是否允许 USB 调试」，选择「始终允许」。

验证是否识别成功：

bash 复制代码

adb devices

如果看到设备序列号，说明连接成功。

⚠️ 如果 adb devices 显示 unauthorized，在手机上重新确认 USB 调试授权弹窗。

5.2 iOS 真机调试

iOS 真机调试需要苹果开发者账号，有两种方式：

免费方式（有限制）：

用个人 Apple ID 登录 Xcode（Xcode → Preferences → Accounts）
应用每 7 天需要重新签名
每台设备最多安装 3 个应用

付费方式（Apple Developer Program，99 美元/年）：

无上述限制
可以发布到 App Store

连接 iPhone 到 Mac，在 Xcode 中信任设备，然后在手机上：设置 → 通用 → VPN 与设备管理 → 信任开发者证书。

六、用 flutter doctor 排查问题

flutter doctor 是 Flutter 自带的环境检查工具，把问题一次性列出来，是排查环境问题的首选命令。

bash 复制代码

flutter doctor

6.1 解读输出结果

正常输出长这样：

复制代码

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.x.x)
[✓] Android toolchain - develop for Android devices
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Android Studio (version 2023.x)
[✓] VS Code (version 1.x)
[✓] Connected device (2 available)
[✓] Network resources

每一行前面的符号含义：

[✓] 正常，没问题
[!] 有警告，通常不影响运行，但建议修复
[✗] 错误，需要处理

6.2 常见错误及解决方法

错误一：Android toolchain - Android license status unknown

bash 复制代码

# 执行以下命令，全部选 y 同意许可
flutter doctor --android-licenses

错误二：Xcode not installed or outdated

确认 Xcode 已安装，然后执行：

bash 复制代码

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

错误三：CocoaPods not installed

bash 复制代码

sudo gem install cocoapods
# 或者
brew install cocoapods

错误四：No connected devices

这只是说明当前没有模拟器在运行或没有连接真机，不是真正的错误，启动模拟器或连接设备后会消失。

错误五：Unable to locate Android SDK

在 Android Studio 的 SDK Manager 里找到 SDK 安装路径，然后：

bash 复制代码

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

七、创建并运行第一个 Flutter 项目

环境配置完成后，验证一下是否真的可以运行：

bash 复制代码

# 创建新项目
flutter create my_first_app

# 进入项目目录
cd my_first_app

# 查看可用设备
flutter devices

# 运行（会自动选择可用设备）
flutter run

看到手机或模拟器上出现 Flutter 的默认计数器应用，环境搭建就算完成了。

总结：常见卡点速查

卡点	原因	解决方式
flutter command not found	环境变量没配好	检查 PATH，重启终端
模拟器启动慢或卡死	未开启硬件加速	开启 HAXM 或 Hyper-V
M 系列 Mac 模拟器慢	选了 x86 镜像	改选 arm64 镜像
adb devices unauthorized	未授权 USB 调试	手机上重新确认弹窗
Android license unknown	未同意 Android 许可	运行 flutter doctor --android-licenses
CocoaPods 报错	未安装或版本问题	brew install cocoapods
依赖下载慢	未配置国内镜像	配置 PUB_HOSTED_URL 环境变量

环境搭好之后，下一步是学习 Dart 语言基础，再进入 Flutter Widget 的世界。加油 🚀