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

写在前面

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

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

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

一、Flutter SDK 安装与配置

1.1 下载 SDK

打开 Flutter 官网：flutter.dev

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

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

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

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

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

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

macOS / Linux：

# 解压到 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 为例）：

# 打开配置文件nano ~/.zshrc # 在文件末尾添加exportPATH="$PATH:$HOME/development/flutter/bin"# 保存后执行让配置生效source ~/.zshrc 

Windows：

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

验证配置是否生效：

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），需要耐心等待。

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

# 同意 Xcode 许可协议（必须做，否则后续步骤会报错）sudo xcodebuild -license accept # 安装 Xcode 命令行工具sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer sudo xcodebuild -runFirstLaunch

4.2 启动 iOS 模拟器

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

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

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

4.3 安装 CocoaPods

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

sudo gem install cocoapods 

⚠️ 如果遇到权限问题或版本冲突，推荐用 Homebrew 安装：

五、真机调试配置

5.1 Android 真机调试

第一步：开启开发者选项

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

第二步：开启 USB 调试

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

第三步：连接电脑

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

验证是否识别成功：

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 自带的环境检查工具，把问题一次性列出来，是排查环境问题的首选命令。

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

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

错误二：Xcode not installed or outdated

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

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

错误三：CocoaPods not installed

sudo gem install cocoapods # 或者 brew install cocoapods 

错误四：No connected devices

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

错误五：Unable to locate Android SDK

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

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

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

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

# 创建新项目 flutter create my_first_app # 进入项目目录cd my_first_app # 查看可用设备 flutter devices # 运行（会自动选择可用设备） flutter run 

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

总结：常见卡点速查

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