Gradle路径配置全解析：解决C盘爆满与Android Studio迁移问题

半个月前同事把项目交给我维护，我打开 Android Studio 第一件事就是 Sync，结果进度条卡在 Gradle 下载那一步，十分钟过去纹丝不动。我看了一眼他的电脑，C 盘已经红了 30 个 G，默认路径下躺着好几个版本的 Gradle 缓存，加起来快 8 个 G。他自己也纳闷：明明没装几个软件，C 盘怎么就爆了？我当时就笑了——Android Studio 的 Gradle 路径问题，几乎每个入坑 Android 开发的人都要踩一遍。

这个话题看起来是“修改 Gradle 路径”这种基础操作，实际上牵扯到好几个层面：全局的 GRADLE_USER_HOME、单个项目里的 gradle-wrapper.properties、Android Studio 的 Gradle JDK 设置、还有下载超时和版本不兼容这一堆连锁反应。很多人搜了一圈教程，照着改了环境变量，结果项目依然在旧路径找东西，或者 Sync 报错直接麻了。这篇文章我会把这几个层面全部掰开揉碎讲清楚，怎么改、为什么这么改、改完最容易在哪翻车，一次性说透。

1. 先搞清楚：Android 项目里其实躺着好几层“Gradle 路径”

很多新手上来就说“我要改 Gradle 路径”，但 Gradle 路径不是单一的一个地址，它至少分三层。如果没分清这三层就盲目去改，大概率是改了 A 处，程序却去 B 处找文件，最后报错报得莫名其妙。

1.1 第一层：GRADLE_USER_HOME，全局缓存主目录

这一层是几乎所有 Gradle 共用的主目录，英文叫 GRADLE_USER_HOME，在 Windows 上默认是 C:\Users\你的用户名\.gradle，macOS / Linux 下是 ~/.gradle。

这个目录里放了三类东西，我分别说：

• wrapper/dists：Gradle Wrapper 下载下来的 Gradle 发行包解压目录，每个版本一个子目录。你的项目声明用 Gradle 7.4 还是 8.7，第一次构建时都会先从网上下载对应版本存到这里。这里也是体积增长最快的地方，随随便便几个版本就是好几个 G。
• caches：项目依赖的缓存，所有通过 Gradle 拉取的第三方库（AndroidX、OkHttp、Glide 等）解压和编译后的缓存都在这。这个目录删了其实不会坏，就是下次构建要重新下载，特别折磨人。
• daemon：Gradle 后台守护进程的日志和临时文件。偶尔有构建问题需要排查时你会来看日志。

平时大家抱怨“C 盘空间越来越小”“Gradle 下载的东西到底放哪了”，绝大多数指的就是这个 .gradle 目录。所以如果你想把 Gradle 相关文件整个挪到 D 盘或者移动硬盘，核心操作就是改 GRADLE_USER_HOME 环境变量。

1.2 第二层：项目里的 gradle-wrapper.properties，版本分发入口

每个 Android 项目根目录下都有一个 gradle/wrapper/gradle-wrapper.properties 文件，它里面的核心配置是 distributionUrl。

举个例子：

properties复制distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

这里的 distributionUrl 决定了这个项目用哪个 Gradle 版本，也决定了它要去哪里下载。它下载后解压到哪里？就是第一层说的 GRADLE_USER_HOME/wrapper/dists/ 下对应的子目录。

所以说，distributionUrl 里的路径其实是一个“相对路径”，它最终指向哪个绝对路径，取决于第一层 GRADLE_USER_HOME 被设置到哪里。我见过不少人只改 distributionUrl 去换版本，却没意识到下载缓存依然写到默认的 C:\Users\用户名\.gradle 里，最后 C 盘还是继续膨胀——这就是没搞清楚第一层和第二层关系导致的典型结果。

1.3 第三层：Android Studio 里的 Gradle JDK 配置

严格来说 Gradle JDK 配置的不是“Gradle 路径”，而是“运行 Gradle 时用的 JVM 路径”。但热搜词里那个 project's gradle version 6.7.1 is incompatible with the gradle jvm version 报错，以及很多改完路径后 Sync 失败的案例，到最后都是卡在这一层。Android Studio 默认会带一个 JetBrains Runtime，版本通常比较新；但老项目用的 Gradle 6.x 可能跑不了太新的 JDK。这个细节我会在第四章专门讲，因为它