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

林瞅瞅2026-10-16 15:42

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

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

1. 概览

阶段 结果
需求确认 目标平台：Android + Web；SDK 装到 E:\flutter；Git clone 方式
Flutter SDK 3.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_URL https://pub.flutter-io.cn Dart 包（pub 依赖）下载镜像
FLUTTER_STORAGE_BASE_URL https://storage.flutter-io.cn Flutter 引擎/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. 创建项目

powershell 复制代码 
cd e:\others\flutter-project
flutter create hello_flutter

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

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

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

现象

powershell 复制代码 
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 下载失败（被墙）

现象

powershell 复制代码 
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 换成腾讯镜像：

properties 复制代码 
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.3.1-all.zip

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

问题 3：NDK 找不到

现象

powershell 复制代码 
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，解压并把顶层目录重命名放到：

makefile 复制代码 
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 SDK E:\flutter（3.47.7）
Android SDK C:\Users\Administrator\AppData\Local\Android\sdk（36.0.0）
NDK 28.2.13676358
模拟器 Medium_Phone_API_37.0
Chrome 系统自带
国内镜像 pub / storage / Gradle（腾讯）

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

7. 常用命令速查

powershell 复制代码 
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 右侧 ▶
  • 方式二（命令行）：
powershell 复制代码 
& "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，重复/冲突条目会导致「旧的好条目被新的坏条目挡住」。
相关推荐
FungLeo5 小时前
成为全栈·Flutter App 篇·Markdown 编辑器：编辑、预览与离开保护
flutter·移动开发·markdown编辑器·表单设计·成为全栈·草稿保存
FungLeo6 小时前
成为全栈·Flutter App 篇·会员中心：资料、密码、通知与私有数据缓存
flutter·dart·身份认证·数据隔离·成为全栈·会员中心
穆梓兰煊1 天前
Flutter端云协同推理架构解析
flutter·github
FungLeo1 天前
成为全栈·Flutter App 篇·内置 WebView：网页历史、App 返回与外链安全
flutter·网络安全·移动开发·webview·路由管理·成为全栈
m0_738185821 天前
Flutter 鸿蒙化实战：volume_controller 适配 OpenHarmony，系统音量控制
flutter·华为·harmonyos·鸿蒙
FungLeo1 天前
成为全栈·Flutter App 篇·Flutter Markdown 阅读器：支持范围与渲染边界
flutter·markdown·dart·代码高亮·成为全栈·移动阅读
m0_738185821 天前
Flutter 鸿蒙化实战：webview_cookie_manager 适配 OpenHarmony，WebView Cookie 管理
flutter·华为·harmonyos·鸿蒙
FungLeo1 天前
成为全栈·Flutter App 篇·服务端目录与文章辅助阅读：锚点、上下篇、浏览量和阅读历史
flutter·锚点·阅读体验·成为全栈·markdown目录·api契约
热门推荐
01「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05几个好用的ip纯净度检测网站06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）08Telegram APK 下载安装完整指南 — 2026年最新09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地