很多人学 Flutter,第一个遇到的拦路虎不是 Widget 嵌套,也不是状态管理,而是开发环境初始化。我见过不少同学在群里问“为什么我的 flutter doctor 一片红”,最后装到一半就放弃了。这篇内容把我从零初始化 Flutter 开发环境的完整过程拆开,从系统准备、SDK 下载、镜像配置,到 Android 工具链、编辑器插件,再到第一个项目跑起来的完整链路,一次讲清楚。适合两类人:一是刚接触 Flutter、还不清楚该装什么的纯新手;二是装过但环境不干净、想彻底重新整理一遍的老手。
1. 初始化前先想清楚:Flutter环境到底包含几条链
很多教程上来就让你下载 SDK,双击解压,然后加 PATH,看起来很简单。但实际装完你会发现,flutter doctor 依然给你列出四五个红叉。问题出在认知上:Flutter 不是一个“装完即用”的独立软件,它是一条完整的工具链,每个环节都缺一不可。
- Flutter SDK 本体:包含 Dart SDK、Flutter 引擎、命令行工具
flutter,这相当于发动机。 - Android 构建链:JDK + Android SDK + Gradle。你要跑 Android 应用,就必须有这套东西,相当于变速箱和轮胎。
- 开发工具:VS Code 或 Android Studio,加上对应的 Flutter 插件,这是你的方向盘和仪表盘。
三者缺一不可。只装 SDK 不做构建链,flutter create 能成功,但 flutter run 一到 Gradle 阶段就会扑街;只装构建链不装编辑器,你连代码都写不了几行。
还有一个隐形环节是设备,包括 Android 模拟器、Chrome 浏览器,或者一台开了开发者模式的真机。这些不是必需项,但直接影响你调试的体验。很多人环境“装好了”却看不到设备,问题往往出在 Android 工具链没有彻底跑通。
搞清这个整体结构后,再往下走就不会迷茫了。接下来我会按正常安装顺序,把每一步怎么操作、为什么这么做、踩了哪些坑都写清楚。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的系统准备:Git与JDK的细节
2.1 为什么非要先装 Git
Flutter 官方文档把 Git 列为必装项。原因不只是版本管理,更核心的是 Flutter 的依赖拉取机制会调用 Git 命令。flutter pub 在解析某些 Git 源依赖时,如果没有 Git 环境,会直接报 “Unable to locate git executable” 之类的错误。Windows 用户建议装 Git for Windows,安装时一路默认即可,但有几个选项要注意:
- 在“Adjusting your PATH environment”这一步,选 Git from the command line and also from 3rd-party software。
- 换行符转换选默认的 “Checkout Windows-style, commit Unix-style line endings” 就行,Flutter 项目本身不涉及混用仓库。
- 装完在终端里执行
git --version能正常输出版本号,就说明没问题。
macOS 用户可以直接用 Xcode Command Line Tools 附带的 Git,执行 xcode-select --install 即可。也可以走 Homebrew 装新版 Git,两者都可以,完全看个人习惯。注意不要在 Windows 上用 winget 装 Git 后忘记重启终端,环境变量不会自动刷新,很多人卡在这一步。
2.2 JDK 版本选择与配置误区
JDK 是 Flutter 做 Android 构建时绕不开的依赖。这里有个容易踩的坑:不是越新越好。 Flutter 官方对 Java 版本有明确建议,目前稳定版推荐 JDK 17。JDK 21 甚至更新的版本,在 Gradle 兼容性上偶尔会出现奇怪的问题,尤其是旧项目迁移上来的场景。
如果你选择了安装 Android Studio,其实可以跳过手动装 JDK 这一步,因为 Android Studio 自带了一个 JetBrains Runtime(JBR),它就是完整可用的 JDK 环境。flutter doctor 检测到 Android Studio 时,会自动定位到它内置的 JDK,不需要额外配置 JAVA_HOME。
但如果你是“纯命令行流派”,不打算装 Android Studio,那就手动装 JDK 17,并配置好两个环境变量:
code复制JAVA_HOME=C:\Program Files\Java\jdk-17
PATH=%JAVA_HOME%\bin;%PATH%
macOS 同理,在 ~/.zshrc 里加上:
code复制export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$
