Flutter Android 开发环境配置全记录

本文记录了从零开始配置 Flutter Android 开发环境的完整过程，包含踩过的坑和对应解决方案。适合有编程基础（Python / JS / Vue）但没有移动端经验的开发者参考。

系统环境：Windows，所有工具安装在 F 盘。

---

目录

1. 整体思路
2. 第一步：创建目录结构
3. 第二步：配置系统环境变量
4. 第三步：安装 Git
5. 第四步：安装 Flutter SDK
6. 第五步：安装 Android Studio
7. 第六步：配置 Gradle 镜像
8. 第七步：关联 Flutter 与 Android SDK
9. 第八步：验证与运行第一个项目
10. 遇到的问题与解决方案

---

整体思路

Flutter Android 开发涉及 4 套独立的网络下载，国内都需要配置镜像才能正常使用：

下载内容	镜像方案
Flutter SDK 本体	FLUTTER_STORAGE_BASE_URL 环境变量
Pub 第三方依赖包	PUB_HOSTED_URL 环境变量
Gradle 依赖库（Maven）	init.gradle 全局配置
Gradle 本体 ZIP	gradle-wrapper.properties 替换下载源

⚠️ 重要：先配镜像，再安装工具，否则下载会超时或极慢。

默认情况下 Android Studio 相关工具会占用 C 盘 10GB 以上，建议全部安装到其他盘：

内容	默认位置	占用大小
Android Studio IDE	C:\Program Files	~1.5 GB
Android SDK	C:\Users\用户名\AppData\Local\Android	~3–5 GB
AVD 模拟器镜像	C:\Users\用户名.android\avd	~3–8 GB
Gradle 缓存	C:\Users\用户名.gradle	~1–3 GB

---

第一步：创建目录结构

在 F 盘提前建好统一的目录结构，便于后续管理：

F:\AndroidStudio\       ← Android Studio IDE 本体
F:\Android\SDK\         ← Android SDK
F:\Android\AVD\         ← 模拟器镜像
F:\Android\Gradle\      ← Gradle 缓存
F:\dev\flutter\         ← Flutter SDK
F:\dev\projects\        ← 你的项目

路径中不能含有中文和空格，否则部分工具会报路径解析错误。

---

第二步：配置系统环境变量

打开方式：控制面板 → 系统 → 高级系统设置 → 环境变量 → 系统变量

新建以下 4 条变量

变量名	变量值	作用
FLUTTER_STORAGE_BASE_URL	https://storage.flutter-io.cn	Flutter SDK 下载镜像
PUB_HOSTED_URL	https://pub.flutter-io.cn	Pub 包管理镜像
ANDROID_AVD_HOME	F:\Android\AVD	模拟器存储路径
GRADLE_USER_HOME	F:\Android\Gradle	Gradle 缓存路径

在 Path 中新增一条

F:\dev\flutter\bin

⚠️ 配置完环境变量后，必须重新开一个 PowerShell 窗口才能生效，不能在原窗口继续操作。

---

第三步：安装 Git

Flutter 依赖 Git 管理 SDK。前往 git-scm.com 下载安装。

安装时选择：Git from the command line and also from 3rd-party software

验证安装：

git --version

---

第四步：安装 Flutter SDK

1. 前往 flutter.cn 下载最新稳定版 ZIP
2. 解压到 F:\dev\flutter\（注意路径无中文、无空格）
3. 已将 F:\dev\flutter\bin 加入 Path（第二步已完成）

验证安装（新开 PowerShell）：

flutter --version

---

第五步：安装 Android Studio

5.1 安装 IDE 本体

前往 developer.android.google.cn/studio 下载安装包。

安装向导第二步 Choose Install Location 改为：

F:\AndroidStudio

5.2 首次启动配置 SDK 路径

首次启动进入 Setup Wizard，在 SDK 路径一栏填写：

F:\Android\SDK

勾选安装：

• Android SDK
• Android SDK Platform-Tools
• Android Emulator

5.3 安装 Flutter 插件

Settings → Plugins → 搜索 Flutter → Install

Dart 插件会随 Flutter 自动安装，安装完成后重启 Android Studio。

5.4 验证 SDK 路径

Settings → Languages & Frameworks → Android SDK → 确认 SDK Location 为 F:\Android\SDK

---

第六步：配置 Gradle 镜像

flutter run 首次编译时会通过 Gradle 下载大量依赖，国内不配镜像会极慢甚至超时。

全局 init.gradle（全局生效，但可能导致gradle冲突）

新建文件 F:\Android\Gradle\init.gradle，写入：

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
    }
}

因为第二步已将 GRADLE_USER_HOME 设为 F:\Android\Gradle\，Gradle 会自动读取该目录下的 init.gradle。

可选：（当上一步冲突导致下载失败时）Gradle 本体下载加速

如果首次 flutter run 卡在下载 Gradle ZIP，打开项目中的：

android/gradle/wrapper/gradle-wrapper.properties

将 distributionUrl 一行替换为（版本号保持原文件一致）：

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

---

版本不稳定导致出现不兼容时

推荐改成稳定版本

AGP: 8.6.0
Gradle: 8.7
Kotlin: 1.9.22
JDK: 17

同样需要先打开项目中的：

android/gradle/wrapper/gradle-wrapper.properties

将 distributionUrl 一行替换为（版本号保持原文件一致）：

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

把android/settings.gradle.kts内的plugins部分改成如下：

plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
    id("com.android.application") version "8.6.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

第七步：关联 Flutter 与 Android SDK

7.1 告诉 Flutter Android SDK 的位置

flutter config --android-sdk F:\Android\SDK

7.2 接受 Android 许可证

flutter doctor --android-licenses

逐一输入 y 回车确认所有许可证。

---

第八步：验证与运行第一个项目

8.1 运行 flutter doctor

flutter doctor

需要以下三项显示绿色 ✓：

[✓] Flutter
[✓] Android toolchain
[✓] Android Studio

Chrome 和 Visual Studio 报红叉可以忽略，不影响 Android 开发。

8.2 创建 Android 模拟器（AVD）

Android Studio → Tools → Device Manager → + → Create Virtual Device

推荐配置：

• Hardware：Pixel 6
• System Image：API 34（Android 14），Google Play 版
• RAM：建议 4GB

8.3 创建并运行第一个项目

flutter create my_app
cd my_app
flutter run

首次运行会下载 Gradle 本体，国内大约需要 5~15 分钟，耐心等待即可。

---

遇到的问题与解决方案

❌ 问题：flutter doctor --android-licenses 报错 sdkmanager not found

报错信息：

Android sdkmanager not found. Update to the latest Android SDK and ensure that
the cmdline-tools are installed to resolve this.

原因： Android SDK Command-line Tools 没有安装，flutter doctor --android-licenses 依赖该工具。

解决方案：

1. 打开 Android Studio
2. Settings → Languages & Frameworks → Android SDK → 点击 SDK Tools 标签
3. 勾选 Android SDK Command-line Tools (latest)
4. 点击 OK，等待下载完成
5. 重新运行：

flutter doctor --android-licenses

---

最终目录结构

配置完成后，F 盘结构如下：

F:\
├── AndroidStudio\          ← IDE 本体
├── Android\
│   ├── SDK\                ← Android SDK + cmdline-tools
│   ├── AVD\                ← 模拟器镜像
│   └── Gradle\
│       └── init.gradle     ← 全局 Gradle 镜像配置
└── dev\
    ├── flutter\            ← Flutter SDK
    └── projects\           ← 你的项目

---

参考资源

• Flutter 中文文档：flutter.cn
• Flutter 中国镜像说明：flutter.cn/community/china
• Android Studio 下载：developer.android.google.cn/studio
• 阿里云 Maven 镜像：maven.aliyun.com

---

作者：LaoQi · LaoQi的秘密基地