Flutter 开发环境从零搭建与调试记录

林思暖
18 阅读5分钟

Flutter 开发环境从零搭建与调试记录

本文件记录在 Windows 机器上从零安装 Flutter 环境、搭建首个项目并调试到成功运行的全部过程，以及过程中遇到问题的根因与解决方案，供后续排查参考。

1. 概览

阶段结果
需求确认目标平台：Android + Web；SDK 装到 E:\flutter；Git clone 方式
Flutter SDK3.47.7 stable（Dart 3.13.5）✅
Android 目标Android Studio + SDK 36 + NDK 28.2 + 模拟器 ✅
Web 目标系统自带 Chrome ✅
编辑器Trae（VS Code 内核）Flutter/Dart 插件 ✅
首个项目 hello_flutter已能 flutter run 正常调试 ✅

2. 初始环境检查

安装前机器的环境现状：

项目初始状态
操作系统Windows 64 位
Git已安装（D:\Program Files\Git，2.53.0）
Flutter / Dart未安装
JDK未安装（随 Android Studio 自带）
Android Studio / SDK未安装
Chrome已存在（C:\Users\Administrator\AppData\Local\Google\Chrome\Bin）
Visual Studio未安装（Windows 桌面开发才需要，本次用不到）
磁盘C 盘约 43 GB，E 盘约 202 GB

3. 安装步骤

3.1 安装 Flutter SDK

  • 位置：E:\flutter
  • 方式：Git clone（便于后续 flutter upgrade 升级）
  • Flutter / Dart 已自动就绪，版本 3.47.7 / 3.13.5

3.2 配置国内镜像（环境变量）

通过 setx 写入用户级环境变量（永久生效）：

变量名值用途
PUB_HOSTED_URLhttps://pub.flutter-io.cnDart 包（pub 依赖）下载镜像
FLUTTER_STORAGE_BASE_URLhttps://storage.flutter-io.cnFlutter 引擎/SDK 工件下载镜像

3.3 配置 PATH

将 E:\flutter\bin 加入用户 PATH，使 flutter 命令可在任意终端直接使用。

3.4 配置 Web 目标（Chrome）

系统自带 Chrome，设置环境变量指向它：

  • CHROME_EXECUTABLE = C:\Users\Administrator\AppData\Local\Google\Chrome\Bin\chrome.exe（按实际路径）

3.5 配置 Android 目标

  1. 安装 Android Studio（国内镜像下载，速度快）：developer.android.google.cn/studio/
  2. 安装过程弹出「Setup Proxy」——直接点 Cancel（仅是无法拉取附加组件列表的警告，不影响安装）
  3. 首次启动选 Standard，自动安装 SDK 组件
  4. 补装 cmdline-tools（Flutter 报缺时，从腾讯镜像下载）
  5. 接受许可证：flutter doctor --android-licenses

最终 Android 相关路径与版本：

  • SDK 根目录：C:\Users\Administrator\AppData\Local\Android\sdk
  • SDK 平台：36.0.0
  • NDK：28.2.13676358（r28c）
  • 模拟器 AVD：Medium_Phone_API_37.0（Android 17 / API 37）

4. 创建项目

cd e:\others\flutter-project
flutter create hello_flutter

生成项目后，flutter run 可分别在 Android 模拟器 / Chrome 上运行。

5. 运行与调试问题排查（重点）

问题 1：error launching git —— git 不在 PATH

现象

flutter devices
error launching git:
Invoke-Expression : 不能对 Null 值表达式调用方法。
Error: Unable to determine engine version...

根因

flutter 启动时要用 git 确定引擎版本，但当前终端 PATH 里没有 git。

解决

把 git 加入用户 PATH（git 在 D:\Program Files\Git）。

问题 2：Gradle 下载失败（被墙）

现象

Exception in thread "main" java.net.UnknownHostException: release-assets.githubusercontent.com
Error: Gradle task assembleDebug failed with exit code 1

根因

Gradle 发行包默认从 services.gradle.org（会重定向到 GitHub 的 release-assets.githubusercontent.com）下载，国内无法直连。

解决

修改 android/gradle/wrapper/gradle-wrapper.properties，把 distributionUrl 换成腾讯镜像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.3.1-all.zip

说明：这是一次性修改，后续新项目都建议做同样处理。

问题 3：NDK 找不到

现象

Package ndk not found.
Package 28.2.13676358 not found.
> Android sdkmanager did not install NDK 28.2.13676358 into C:\...\Android\sdk.

根因

新版 Android CLI 自动安装 NDK 失败（源不可达/组件缺失）。

解决

手动从腾讯/阿里镜像下载 android-ndk-r28c-windows.zip，解压并把顶层目录重命名放到：

C:\Users\Administrator\AppData\Local\Android\sdk\ndk\28.2.13676358

要求该目录下存在 source.properties，且 Pkg.Revision = 28.2.13676358。

问题 4：git 命令全局失效（根因分析）

现象

装完 Flutter 环境后，git 命令全局无法访问，flutter run 报 error launching git。

排查过程与根因

用完整路径直接测试，发现：

路径类型结果
D:\Program Files\Git\mingw64\bin\git.exe真正的 git✅ 正常
D:\Program Files\Git\cmd\git.exe启动器✅ 正常
D:\Program Files\Git\bin\git.exe启动器❌ error launching git

关键点：

  • Git 安装时，系统级 PATH 里本来就有正确的 D:\Program Files\Git\cmd。
  • 安装 Flutter 时，误把坏的 D:\Program Files\Git\bin 加进了用户级 PATH。
  • Windows 中用户 PATH 优先级高于系统 PATH，于是 git 一直被引导到坏的 bin\git.exe，把好的 cmd\git.exe 挡住了。

解决

从用户级 PATH 中删除 D:\Program Files\Git\bin 这一条，让 git 回落到系统 PATH 里正确的 cmd 上。

教训

  • Git for Windows 的 bin\git.exe 是在 MSYS2 环境下用的启动器，不能当作独立命令放进 PATH。
  • 放进 PATH 的应该是 Git\cmd（Windows 命令行启动器）。
  • 排查「命令找不到/报错」时，先用完整路径直接运行来区分「PATH 没配好」还是「程序本身坏了」。

6. 最终状态

组件位置 / 版本
Flutter SDKE:\flutter（3.47.7）
Android SDKC:\Users\Administrator\AppData\Local\Android\sdk（36.0.0）
NDK28.2.13676358
模拟器Medium_Phone_API_37.0
Chrome系统自带
国内镜像pub / storage / Gradle（腾讯）

flutter doctor 结果中除「Visual Studio」（Windows 桌面开发才需要）外，其余全部通过。

7. 常用命令速查

flutter devices          # 查看可用设备（模拟器 / Chrome）
flutter run              # 运行当前项目（自动选择设备）
flutter run -d emulator-5554   # 指定运行到模拟器
flutter create my_app    # 新建项目
flutter doctor           # 排查环境问题
flutter doctor --android-licenses  # 接受 Android 许可证

启动模拟器（手动）：

  • 方式一（推荐）：Android Studio → Device Manager → 点 AVD 右侧 ▶
  • 方式二（命令行）：
& "C:\Users\Administrator\AppData\Local\Android\Sdk\emulator\emulator.exe" -avd Medium_Phone_API_37.0

8. 踩坑心得总结

  1. 国内网络是最大变量：Flutter pub、SDK 工件、Gradle 都要走国内镜像，否则下载卡死。
  2. 环境变量改动需重启进程：setx 只影响之后新启动的进程，改了 PATH 后要彻底重启 Trae（不只是新开终端）。
  3. 排查命令问题时先定位是 PATH 还是程序本身：用完整路径直接跑最直接。
  4. PATH 优先级坑：用户 PATH 覆盖系统 PATH，重复/冲突条目会导致「旧的好条目被新的坏条目挡住」。
avatar
文章
阅读
粉丝