Windows 安装 Flutter 开发环境详细教程（JDK17 + Android Studio + 模拟器）

Flutter 新项目初始化与 Android 运行问题排查实战

记录一次 Flutter 新项目从初始化、配置国内镜像、补齐平台代码，到运行 Android 模拟器过程中遇到的问题排查。
这篇文章适合刚开始搭建 Flutter 项目，或者在 Windows 环境下跑 Flutter Android 工程时频繁踩坑的同学参考。

---

前言

最近在初始化一个 Flutter 项目时，原本以为只是简单跑个 demo，结果实际过程中连续遇到了不少问题，比如：

• 平台工程不完整
• Gradle 下载慢
• Maven 仓库拉取依赖失败
• Android 网络权限遗漏
• 命令执行目录不对
• 误把 flutter pub get 写成了 flutter pub add get
• Windows 未开启开发者模式，导致插件无法创建 symlink

所以这篇文章把整个过程整理成一份完整记录，尽量做到从零到可运行，一步一步说清楚。

---

---

一、补齐其他平台代码

如果当前 Flutter 工程缺少平台目录，或者工程不完整，可以先在项目根目录执行：

flutter create .

执行后，Flutter 会自动补齐缺失的平台代码，比如：

• android
• ios
• windows
• linux
• macos

这里没有 ohos 平台是正常的，因为官方 Flutter 默认并不直接支持鸿蒙平台。如果要适配鸿蒙，一般需要特定版本或者专门的适配方案。

---

二、设置 Gradle 和 Maven 仓库

在国内网络环境下，Flutter Android 项目如果不配镜像，经常会出现 Gradle 下载慢、依赖拉不下来、构建失败等问题。

---

2.1 设置 Gradle 地址

打开文件：

android/gradle/wrapper/gradle-wrapper.properties

将 distributionUrl 改成国内镜像地址：

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

这样做的目的很直接：让 Gradle 包下载更快、更稳定。

---

2.2 修改 Gradle 的 Maven 仓库镜像地址

在 Gradle 对应配置文件中，加入下面这些国内仓库镜像：

maven { url = uri("https://maven.aliyun.com/repository/google") }
maven { url = uri("https://maven.aliyun.com/repository/releases") }
maven { url = uri("https://maven.aliyun.com/repository/central") }
maven { url = uri("https://maven.aliyun.com/repository/public") }
maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
maven { url = uri("https://maven.aliyun.com/repository/apache-snapshots") }
maven { url = uri("https://maven.aliyun.com/nexus/content/groups/public/") }
maven { url = uri("https://jitpack.io") }

这一步主要是为了避免 Android 构建时卡在依赖下载阶段。

---

三、设置安卓网络权限

如果项目中需要访问接口、请求图片、调用网络资源，一定不要漏掉 Android 网络权限。

在 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.INTERNET" />

通常这个文件位置在：

android/app/src/main/AndroidManifest.xml

很多人第一次写接口请求时，代码没问题，但请求一直失败，最后排查才发现是权限没配。

---

四、运行到模拟器

基础配置完成之后，就可以直接运行到模拟器，比如 Android Emulator。

执行：

flutter run

如果设备正常连接，Flutter 就会自动编译并安装到模拟器中。

---

五、实际排查过程中遇到的问题

上面的步骤只是初始化流程，真正麻烦的是后面实际运行时暴露出来的问题。下面这几个坑，我这次基本都踩了一遍。

---

5.1 flutter clean 报错：No pubspec.yaml file found

错误信息如下：

C:\Users\92199>flutter clean
Error: No pubspec.yaml file found.
This command should be run from the root of your Flutter project.

原因

这个问题本质上不是 Flutter 环境坏了，而是 命令执行目录不对。

flutter clean、flutter pub get、flutter run 这些命令，都要求你当前所在目录必须是 Flutter 项目根目录，也就是和 pubspec.yaml 同级。

你如果在：

C:\Users\92199

这种普通目录下执行，就一定会报这个错。

正确做法

先进入项目根目录，再执行命令：

cd /d D:\project\flutter_test_project
flutter clean
flutter pub get
flutter run

建议

不确定当前目录对不对时，先执行：

dir

看一下有没有这个文件：

pubspec.yaml

有，说明目录对了；没有，就说明你还没进入项目根目录。

---

5.2 把 flutter pub get 误写成了 flutter pub add get

这个坑特别容易踩。

很多人本来想执行：

flutter pub get

结果手快输成了：

flutter pub add get

表面上看就差一个单词，但含义完全不同。

flutter pub get

作用是：拉取当前项目已有依赖

flutter pub add get

作用是：给项目新增一个叫 get 的依赖包

也就是说，这不是“安装依赖”的普通命令，而是相当于把 GetX 这个包写进 pubspec.yaml 里了。

如果是误操作，可以执行：

flutter pub remove get

把它删掉。

---

5.3 Building with plugins requires symlink support

在添加插件，比如：

flutter pub add shared_preferences

之后，再执行 flutter pub get，出现了下面这个报错：

Building with plugins requires symlink support.

Please enable Developer Mode in your system settings.
Run
  start ms-settings:developers
to open settings.

原因

这是因为 Windows 没有开启开发者模式，而 Flutter 在构建带插件的项目时，需要创建符号链接（symlink）。

像 shared_preferences 这种插件，不只是 Dart 层代码，还会带平台相关实现。Windows 下如果系统没开开发者模式，就会卡在这里。

解决办法

直接执行：

start ms-settings:developers

系统会自动打开 Windows 开发者设置页面。

然后把：

开发人员模式

打开即可。

开启之后，重新打开终端，再执行：

flutter clean
flutter pub get
flutter run

基本就能继续往下走了。

---

六、推荐的完整初始化顺序

结合这次实际操作，我建议 Flutter 新项目初始化按下面这个顺序来做。

第一步：补齐平台代码

flutter create .

第二步：修改 Gradle 镜像

修改：

android/gradle/wrapper/gradle-wrapper.properties

内容改成：

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

第三步：配置 Maven 镜像

把阿里云等国内仓库地址补进去。

第四步：配置 Android 网络权限

<uses-permission android:name="android.permission.INTERNET" />

第五步：如果使用插件，先开启 Windows 开发者模式

start ms-settings:developers

第六步：确认在项目根目录执行命令

flutter clean
flutter pub get
flutter run

---

七、总结一下这次踩坑点

这次排查下来，我最大的感受是：

Flutter 项目刚开始跑不起来，很多时候不是代码逻辑问题，而是工程和环境问题。

常见坑主要有这些：

• 工程平台代码没补齐
• Gradle 和 Maven 下载太慢
• Android 权限没配
• 命令没有在项目根目录执行
• 把 flutter pub get 写成了 flutter pub add get
• Windows 没开启开发者模式，导致插件构建失败

这些问题看起来都不复杂，但如果第一次遇到，很容易来回绕很久。

---

八、文末命令汇总

# 补齐平台代码
flutter create .

# 清理项目
flutter clean

# 获取依赖
flutter pub get

# 添加插件
flutter pub add shared_preferences

# 删除误加的 get 依赖
flutter pub remove get

# 运行项目
flutter run

# 查看环境
flutter doctor -v

# 打开 Windows 开发者模式设置
start ms-settings:developers

---

九、写在最后

如果你也是在 Windows 下搭 Flutter 新项目，建议一开始就把下面几件事做了：

• 平台工程补齐
• Gradle 镜像改国内源
• Maven 仓库换镜像
• Android 网络权限提前加上
• Windows 开发者模式先打开
• 所有 Flutter 命令都在项目根目录执行

这样后面会省掉很多无效排查时间。

如果这篇文章对你有帮助，欢迎点赞、收藏，也欢迎一起交流 Flutter 开发中遇到的坑。

---

文章标题建议

你发 CSDN 时，标题可以用下面这几个里任意一个：

版本一

Flutter 新项目初始化与 Android 模拟器运行问题排查实战

版本二

Flutter 项目从创建到运行完整踩坑记录：Gradle、权限、symlink 问题一次讲清

版本三

Flutter Windows 环境下新项目运行失败排查：pubspec、插件 symlink、Gradle 镜像全记录

---

标签建议

发 CSDN 时可以加这几个标签：

Flutter
Android
Gradle
Dart
Windows
移动开发
问题排查

；