Flutter 开发环境搭建

NOTE

当前文档仅在以下环境中真实验证过

MacBook Air（13英寸，M4，2025年）
芯片：Apple M4
内存：16GB
macOS：15.6.1

1. 搭建开发环境

1.1 搭建基础环境

1.1.1 安装 Xcode 软件

Xcode：https://developer.apple.com/cn/xcode/

升级Xcode通过App Store升级即可

1.1.2 设置 Xcode 命令行工具

设置Xcode命令行工具为上一小节安装的Xcode

bash

sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
# 命令解释：
# sudo：提权执行命令（以超级用户（root / 管理员）身份执行后续命令）
# sh -c '...'：批量执行引号内的命令
# xcode-select -s /Applications/Xcode.app/Contents/Developer：切换默认开发者工具路径
# &&：命令执行的「逻辑与」控制（只有前面的命令执行成功（返回值为 0），才会执行后面的命令）
# xcodebuild -runFirstLaunch：自动化完成 Xcode 首次初始化，模拟「Xcode 首次手动打开」的交互流程

验证上一步是否设置成功

bash

xcode-select -p
# 命令解释：
# xcode-select：macOS 专属的「开发者工具路径管理命令」
# -p：是 print 的缩写，核心作用是「打印（Print）当前系统的活跃开发者目录

输出如下内容则表示成功：

/Applications/Xcode.app/Contents/Developer

1.2 安装 Flutter SDK

1.2.1 下载 Flutter SDK

访问 Flutter SDK 下载网站
选择适用于macOS系统的Stable channel版本SDK进行下载
本地创建自定义目录并将上一步下载的SDK压缩包进行解压

1.2.2 配置 Flutter SDK

~/.zprofile 文件中添加以下内容进行 SDK 配置

bash

export PATH="<path-to-sdk>/bin:$PATH"

<path-to-sdk>需要替换成 Flutter SDK 解压所在的目录。

执行如下命令应用在 ~/.zprofile 文件中的变更

bash

source ~/.zprofile

1.2.3 验证 Flutter SDK

输入如下命令验证

bash

flutter --version
dart --version

1.2.4 更新 Flutter SDK

bash

flutter upgrade

1.3 配置国内镜像

~/.zprofile 文件中添加以下内容进行镜像地址配置，可加速访问

bash

export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

PUB_HOSTED_URL：Dart/Flutter 依赖包的下载源（类似 npm 的 registry、pip 的 index-url）
FLUTTER_STORAGE_BASE_URL：Flutter SDK / 工具资源的下载源

1.4 安装IDE

推荐使用Visual Studio Code

1.4.1 安装 Flutter 扩展

打开 Visual Studio Code
打开浏览器，访问Flutter扩展页面
点击 Install 按钮唤起 Visual Studio Code 并安装扩展

2. 配置 Android 开发环境

安装 Android Studio：

下载 Android Studio
安装并启动 Android Studio
打开 Settings → Plugins → 安装 Flutter 和 Dart 插件
重启 Android Studio

安装 Android-SDK-Command-line-Tools：

下载：https://developer.android.com/studio?hl=zh-cn#command-line-tools-only
~/Library/Android/sdk目录下创建cmdline-tools/latest目录
将步骤1下载的zip解压到latest目录下，最终：～/Library/Android/sdk/cmdline-tools/latest/bin
配置环境变量到~/.zprofile：export PATH="～/Library/Android/sdk/cmdline-tools/latest/bin:$PATH"
source ~/.zprofile
sdkmanager --version

接受 Android 许可：

bash

flutter doctor --android-licenses
# flutter doctor：Flutter 自带的环境检测工具
# --android-licenses：调出所有未同意的 Android SDK 许可协议列表，并引导你逐行确认同意

3. 配置 iOS 开发环境

4. 最终检查

bash

flutter doctor -v
# flutter doctor：Flutter 自带的环境检测工具
# -v： verbose 的缩写，让 flutter doctor 输出完整的检测细节

理想状态下，所有项目都应该显示 ✓（绿色对勾）。

🔧 IDE 选择与配置

VS Code（推荐）

优点：

轻量级
启动快
扩展丰富

安装步骤：

下载 VS Code
安装扩展：
- Flutter（官方）
- Dart（官方）
- Flutter Widget Snippets
- Awesome Flutter Snippets

推荐配置（settings.json）：

json

{
  "dart.flutterSdkPath": "/path/to/flutter",
  "dart.previewFlutterUiGuides": true,
  "dart.previewFlutterUiGuidesCustomTracking": true,
  "editor.formatOnSave": true,
  "editor.formatOnType": true,
  "[dart]": {
    "editor.rulers": [80],
    "editor.selectionHighlight": false,
    "editor.suggest.snippetsPreventQuickSuggestions": false,
    "editor.suggestSelection": "first",
    "editor.tabCompletion": "onlySnippets",
    "editor.wordBasedSuggestions": false
  }
}

Android Studio

优点：

功能强大
官方支持好
Android 开发体验最佳

安装步骤：

启动 Android Studio
Preferences → Plugins
搜索并安装：
- Flutter
- Dart
重启 Android Studio

IntelliJ IDEA

与 Android Studio 类似，同样支持 Flutter 插件。

✅ 验证安装

创建测试项目

bash

flutter create test_app
cd test_app

# 运行项目
flutter run

检查设备

bash

# 查看可用设备
flutter devices

# 选择设备运行
flutter run -d <device-id>

常见设备类型

iOS 模拟器：ios 或 simulator
Android 模拟器：Android 设备名称
真机：设备名称
Chrome：chrome
macOS 桌面：macos
Windows 桌面：windows
Linux 桌面：linux

🐛 常见问题

1. Flutter Doctor 显示 Android licenses 未接受

bash

flutter doctor --android-licenses

一路输入 y 接受所有许可。

2. Xcode 版本过旧

bash

# 更新 Xcode
# 在 App Store 更新或下载最新版本

3. iOS 模拟器无法启动

bash

# 重置模拟器
xcrun simctl erase all

# 重新打开
open -a Simulator

4. Android SDK 路径未找到

在 Android Studio 中：

Preferences → Appearance & Behavior → System Settings → Android SDK
记下 Android SDK Location
设置环境变量：

bash

export ANDROID_HOME=/path/to/android/sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools

5. CocoaPods 安装失败

bash

# 使用淘宝镜像
gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
gem sources -l

# 安装 CocoaPods
sudo gem install cocoapods

6. Flutter 命令未找到

确保 Flutter bin 目录已添加到 PATH：

bash

# 临时添加
export PATH="$PATH:/path/to/flutter/bin"

# 永久添加
echo 'export PATH="$PATH:/path/to/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

🚀 下一步

环境搭建完成后，你可以：

👉 了解开发工具 - 学习如何使用开发工具
👉 创建第一个应用 - 学习 Dart 语言
👉 Widget 基础 - 学习 Flutter 组件

📚 参考资源

环境搭建是第一步，祝你顺利！🎉

Flutter 开发环境搭建 ​

1. 搭建开发环境 ​

1.1 搭建基础环境 ​

1.1.1 安装 Xcode 软件 ​

1.1.2 设置 Xcode 命令行工具 ​

1.2 安装 Flutter SDK ​

1.2.1 下载 Flutter SDK ​

1.2.2 配置 Flutter SDK ​

1.2.3 验证 Flutter SDK ​

1.2.4 更新 Flutter SDK ​

1.3 配置国内镜像 ​

1.4 安装IDE ​

1.4.1 安装 Flutter 扩展 ​

2. 配置 Android 开发环境 ​

3. 配置 iOS 开发环境 ​

4. 最终检查 ​

🔧 IDE 选择与配置 ​

VS Code（推荐） ​

Android Studio ​

IntelliJ IDEA ​

✅ 验证安装 ​

创建测试项目 ​

检查设备 ​

常见设备类型 ​

🐛 常见问题 ​

1. Flutter Doctor 显示 Android licenses 未接受 ​

2. Xcode 版本过旧 ​

3. iOS 模拟器无法启动 ​

4. Android SDK 路径未找到 ​

5. CocoaPods 安装失败 ​

6. Flutter 命令未找到 ​

🚀 下一步 ​

📚 参考资源 ​

Flutter 开发环境搭建

1. 搭建开发环境

1.1 搭建基础环境

1.1.1 安装 Xcode 软件

1.1.2 设置 Xcode 命令行工具

1.2 安装 Flutter SDK

1.2.1 下载 Flutter SDK

1.2.2 配置 Flutter SDK

1.2.3 验证 Flutter SDK

1.2.4 更新 Flutter SDK

1.3 配置国内镜像

1.4 安装IDE

1.4.1 安装 Flutter 扩展

2. 配置 Android 开发环境

3. 配置 iOS 开发环境

4. 最终检查

🔧 IDE 选择与配置

VS Code（推荐）

Android Studio

IntelliJ IDEA

✅ 验证安装

创建测试项目

检查设备

常见设备类型

🐛 常见问题

1. Flutter Doctor 显示 Android licenses 未接受

2. Xcode 版本过旧

3. iOS 模拟器无法启动

4. Android SDK 路径未找到

5. CocoaPods 安装失败

6. Flutter 命令未找到

🚀 下一步

📚 参考资源