起因

Flutter 开发环境属于“组件最多”的那类：Flutter SDK、Android SDK、NDK、CMake，背后还隐式依赖 Java 与 Gradle，任何一环没配好，flutter doctor 就亮红灯。这篇记录 Windows 下从零配好一套能编译 Android 工程的 Flutter 环境的完整过程，以及高频报错的根因。

需求

Windows 上配好 Flutter 开发环境，能创建并编译运行 Android 工程
国内网络环境下拉取依赖不卡死
flutter doctor 检查全部通过

配置思路：每步在配什么、为什么

整体依赖关系：Flutter SDK（Dart 工具链与 flutter 命令）→ Android SDK（编译、adb 真机调试）→ NDK + CMake（带原生 C/C++ 代码的插件编译时才用到）。环境变量分两类：PATH 负责让命令行找得到可执行文件；FLUTTER_STORAGE_BASE_URL、PUB_HOSTED_URL 这类变量是给工具链“指路”的镜像开关——Flutter 要从 Google 仓库拉 SDK 二进制和 pub 包，国内直连常常超时，指到国内镜像就通了。

配置flutter的环境变量

flutter环境变量

1
2


FLUTTER_STORAGE_BASE_URL 设置成  https://storage.flutter-io.cn
PUB_HOSTED_URL

两个变量的镜像值（建成系统环境变量即可）：

FLUTTER_STORAGE_BASE_URL = https://storage.flutter-io.cn：Flutter 引擎二进制、Dart SDK 等静态资源的下载源；
PUB_HOSTED_URL = https://pub.flutter-io.cn：pub 包仓库的镜像源，作用相当于 npm 换 registry。

不配这两个变量的典型症状：flutter doctor 卡在下载、flutter packages get 超时——根因都是直连 Google 源极慢或不通。

flutter SDK环境变量

在PATH中添加flutter的sdk路径，PATH 生效后命令行才能找到 flutter、dart 两个命令。我本地的路径，根据你自己的情况修改。

1

E:\flutter_windows_3.0.2-stable\flutter\bin

安卓开发环境配置

Flutter 编译 Android 工程，实际是调用 Android SDK 里的工具链（aapt2、d8、adb 等）。SDK 装在哪要用环境变量“告诉”Gradle 和 Flutter，否则每个工程都得在 local.properties 里重复指一遍。

ANDROID_HOME

打开系统环境变量，新添加环境变量 ANDROID_HOME，值为 Android SDK 的安装目录，构建工具靠它定位 SDK

1

E:\android\android-sdk

NDK_HOME

打开系统环境变量，新添加环境变量 NDK_HOME，值为 NDK 目录。纯 Dart 工程用不到它；一旦依赖带原生 C/C++ 源码的插件，Gradle 会调 NDK 里的交叉编译工具链生成 so 库，找不到它就会在构建阶段报 NDK 相关错误

1

E:\android\android-ndk

修改PATH

在PATH变量中，添加以下环境变量，把 SDK 的各工具目录挂进 PATH：platform-tools 里有 adb（真机调试全靠它）、emulator 是模拟器、tools 是旧版工具集

1
2
3
4
5


%ANDROID_HOME%/tools
%ANDROID_HOME%/tools/bin
%ANDROID_HOME%/emulator
%ANDROID_HOME%/platform-tools
%NDK_HOME%

cmake环境变量配置

在PATH中添加cmake的环境变量。同样是给原生代码用的：现代 NDK 工程的构建标准是 CMake，带原生部分的插件由它生成构建脚本。这里把 SDK 目录里装的这份 cmake 也挂进 PATH，命令行手动构建时同样能找到

1

E:\android\android-sdk\cmake\3.10.2.4988404\bin

报错

Android toolchain - develop for Android devices 这是 flutter doctor 最常见的一项异常，报的是 Android 许可协议没有接受：SDK 组件（build-tools、platforms 等）安装时要逐个同意 Google 的许可，没同意前 Flutter 拒绝使用它们。根因明确，解决就是一条命令批量接受许可（一路 y 下去）：

1

flutter doctor --android-licenses

开启Windows的开发者选项

Windows 默认只允许安装商店来源的应用，开发者模式放开本机调试部署的权限。命令直接跳到设置页：

1

start ms-settings:developers

检测

全部配完用一条命令总检，它会逐项检查 Flutter SDK、Android toolchain、Visual Studio（Windows 桌面开发才需要）并给出每项结论与提示：

1

flutter doctor

踩坑记录与注意事项

镜像变量要在装 SDK 之前配好：FLUTTER_STORAGE_BASE_URL、PUB_HOSTED_URL 是下载时读取的，装完再配只对以后的 pub get 生效——这是“配了镜像还是卡”的常见根因；
改完环境变量要重开终端：环境变量在进程启动时继承，已开的 cmd/VSCode 终端读不到新值，重开终端（VSCode 要整个重启）才生效；
路径别带中文和空格：Gradle、NDK 的部分工具链对空格敏感，ANDROID_HOME 含空格会出现莫名的构建失败；
flutter doctor 报 Android toolchain 异常：先跑 flutter doctor --android-licenses 接受许可；仍不行再查 ANDROID_HOME 指向、sdkmanager 是否可用；
Visual Studio 一项的报错可以先无视：那是开发 Windows 桌面程序用的，只做 Android 不影响；
flutter 命令第一次运行很慢是正常的：首次要下载 Dart SDK 与引擎工件，卡住不动再回头查镜像配置。

Flutter开发环境配置

Contents

起因

需求