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。这个细节我会在第四章专门讲，因为它是“改路径”最容易踩的隐藏坑。

1.4 这三层路径分别该怎么理解

再说多一句，很多教程会让新手去改 local.properties 里的 sdk.dir，那个是 Android SDK 的路径，不是 Gradle 的路径。SDK 和 Gradle 是两个完全不同的东西，一个负责编译 Android 代码时调用平台 API，一个负责整个构建流程编排。改的时候别混了。

2. 实操迁移 GRADLE_USER_HOME：完整步骤和验证方法

理解了上面几层路径后，再动手迁移就心里有数了。这一章我以 Windows 为主完整走一遍迁移流程，macOS/Linux 的操作逻辑一模一样，只是环境变量写入的文件不同。

2.1 迁移前先算一笔账：你到底要挪多大

不要上来就复制，先看看 .gradle 目录占了多大。最简单的办法：在文件资源管理器路径栏输入 %USERPROFILE%\.gradle，回车后右键文件夹看属性。也可以用命令：

bash复制# Windows PowerShell 里运行
du -sh $HOME\.gradle

# macOS / Linux
du -sh ~/.gradle

我见过不少项目其实不大，但 .gradle 目录能到 5~10 个 G。原因通常是同时维护多个历史项目，每个项目的 Gradle 版本都不一样，wrapper/dists 里躺着 6 个版本的完整发行包。如果你手头项目多，这个目录只会越来越大，挪走是唯一一劳永逸的方案。

在动手之前还有一件事：尽量关闭 Android Studio 所有窗口。原因后面会提到，Gradle daemon 进程可能还占着文件，直接剪切容易失败。

2.2 Windows 完整迁移：复制、设变量、重启

第一步，先打开文件资源管理器，把整个 .gradle 文件夹复制到目标位置。比如我想统一管理 Android 开发环境，一般放在 D:\Android\GradleHome\.gradle。注意这里我用的是“复制”，不是“剪切”。迁移这种事，稳妥是第一位的，复制完验证没问题，再把原文件夹删掉，别一开始就把原文件挪走，万一某个文件被占用导致复制不完整，你就两头都没着落。

第二步，设置环境变量。右键“此电脑” → “属性” → “高级系统设置” → “环境变量”，在“用户变量”区域点击“新建”：

code复制变量名：GRADLE_USER_HOME
变量值：D:\Android\GradleHome\.gradle

为什么用用户变量而不是系统变量？因为 Gradle 和 Android Studio 是按当前用户去读这个配置的，用户变量足够用，也不需要管理员权限，干净利落。如果公司电脑有多个用户切换，放用户变量还能避免影响其他人。

macOS 或 Linux 则在 ~/.zshrc（新版 macOS）或 ~/.bashrc 里加一行：

bash复制export GRADLE_USER_HOME=/Users/你的用户名/Android/GradleHome/.gradle

然后 source ~/.zshrc 让它生效。

第三步，重启 Android Studio。这一步很多人漏掉。Android Studio 在启动时会读取一次环境变量，如果你只是开了个新终端窗口去跑 Gradle 命令，它读到的是新变量；但 Android Studio 的进程不会自动刷新，必须完全退出再重新打开。我甚至建议在任务管理器里确认没有 java.exe 或 studio64.exe 残留再重新启动。

2.3 验证是否成功：别靠感觉，看实际产物

改完之后，重新打开项目让它 Sync 一次。等构建跑完，去 D:\Android\GradleHome\.gradle 目录下看看，正常会出现 caches、daemon、wrapper 这些子目录。如果这些目录在几分钟内逐渐出现新文件，说明配置已经生效。

还有一种快速验证方式，在命令行里跑：

bash复制# Windows
echo %GRADLE_USER_HOME%

# macOS / Linux
echo $GRADLE_USER_HOME

如果输出是你期望的新路径，说明环境变量已经正确设置。

这里给你一个真实的体验参考：我上一次从 C 盘迁移到 D 盘的时候，点完 Sync 之后明显感觉启动和构建速度也稳了一些。原因倒不是 D 盘更快，而是原来那个 .gradle 目录里塞了太多历史版本缓存，有些文件索引已经很乱，等于是“新家重新摆了一遍”，带走了很多历史包袱。

2.4 迁移后原文件夹怎么处理

新工程运行一段时间，确认没任何问题后，原 C:\Users\用户名\.gradle 就可以删了。但这里给个保守建议：不要直接删整个文件夹，把它重命名成 .gradle_backup 放在原处，等两周后还能正常构建，再彻底删除。你可能会说“这不一样占着 C 盘吗？”是的，但删数据这种事，给自己留一条后悔药还是很值的。

顺手提一句，如果你 C 盘空间确实紧张，Android Studio 本身的系统缓存（C:\Users\用户名\AppData\Local\Google\AndroidStudio2024.2 这类目录）也占了几个 G。那个在 Android Studio 设置里通过改 IDE 缓存路径解决，跟 Gradle 路径没关系，这篇文章不展开，但知道有这么回事就行。

3. 单项目改造：distributionUrl、国内镜像和离线包的正确姿势

迁移完全局目录，接下来是项目级的问题。如果你在公司网络环境下 Sync 项目，经常卡在下载 Gradle 发行包那一步，或者反复报类似 Could not install Gradle distribution from 'https://services.gradle.org/distributions/gradle-8.10.2-bin.zip' 或 SocketTimeoutException，根因几乎都是：Gradle 官方服务器在你的网络环境下下载太慢、连接不稳定。

这时候就得回到 gradle-wrapper.properties 做文章。

3.1 标准做法：直接改 distributionUrl 换镜像

打开 gradle/wrapper/gradle-wrapper.properties，找到 distributionUrl，把域名从 services.gradle.org 换成国内可达的镜像源。我用腾讯云和华为云都试过，效果都稳定。格式跟官方地址保持一致，只是换域名：

properties复制# 腾讯云镜像示例
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.10.2-all.zip

# 华为云镜像示例
distributionUrl=https\://mirrors.huaweicloud.com/gradle/gradle-8.10.2-bin.zip

改完保存，重新 Sync。Android Studio 会去镜像地址下载同一个版本的 Gradle，速度通常能快很多。这里提醒一句：改完镜像后，下载下来的发行包依然会被缓存到 GRADLE_USER_HOME/wrapper/dists/ 下，而且缓存目录的哈希是基于 distributionUrl 计算出来的，跟你之前从官方地址下载同一个版本时用的目录不一定相同。也就是说，可能之前明明下过 8.10.2，改成镜像地址后它又要重新下一遍，因为 URL 变了哈希就变了。第一次跑的时候耐心等完，后续就不会再重复下载了。

3.2 一次下载彻底解决：把 zip 手动放进缓存目录

如果没有内网镜像，或者公司网络对下载限速，又或者你长时间处于出差、弱网环境，最稳的方案是直接手动下载 zip 包，再放到 wrapper 缓存目录中。

手动放 zip 包时最烦的是缓存子目录名是一长串哈希，比如：

code复制D:\Android\GradleHome\.gradle\wrapper\dists\gradle-8.10.2-all\8a94umvpao1g0eq0l0d6bp7b4k\

这个目录名是根据 distributionUrl 算出来的 MD5 前几位转 base36，不同 URL 对应不同目录，没法直接猜。常规做法是：

1. 先保持原来的 distributionUrl 不变（或者改成你要用的那个 URL），打开项目触发一次 Sync，让它尝试下载几秒钟后超时失败退出。这个过程会在 wrapper/dists 下自动创建好对应的哈希目录。
2. 到那个哈希目录里看，通常会看到类似 gradle-8.10.2-all.zip.part 或 .lck 文件。把 .part 和 .lck 文件删掉。
3. 把从别处下载好的同名 zip 完整文件放进去。
4. 重新 Sync，Gradle Wrapper 检测到 zip 文件已经存在就会直接解压使用，不再走网络下载。

我用这个方法在公司内网机器上救过很多次急。注意 zip 文件命名必须和 distributionUrl 里的完全一致，不然 Wrapper 会认为不是目标文件。

3.3 千万别踩的坑：distributionUrl 改成 zip 了目录对不上

有些教程会告诉你去把 distributionUrl 保持原样、同时复制 zip 进去。但实际操作里最容易出问题的点是：你复制 zip 进去的哈希目录，可能是基于“官方地址的 URL”算出来的；而你最后 Sync 时用的 distributionUrl，如果被人改成了镜像地址，哈希目录又变了，它就不会去读你放好的 zip，而是傻乎乎地继续下载。

我的建议是：离线包方案里，distributionUrl 千万不要换来换去，确认用哪个就把哪个固定住。最常见的操作顺序是：先确认项目 wrapper 里写的是官方地址，留个备份，触发一次下载产生目录，放入 zip，再 sync。这个方法能成功，核心前提就是“URL 没变过”。

3.4 Android Studio 图形界面里的路径设置

如果不想折腾环境变量，Android Studio 设置里也有对应的 GUI 入口。打开 Settings（macOS 上是 Preferences）→ Build, Execution, Deployment → Build Tools → Gradle。

这里有这么几个东西值得关注：

• Gradle user home / Service directory path：对应 GRADLE_USER_HOME。如果你在设置里修改了它，它会优先于系统环境变量生效。换句话说，就算你在系统里设置了 GRADLE_USER_HOME=D:\Android\GradleHome\.gradle，但 IDE 设置里还写着旧的 C:\Users\用户名\.gradle，那构建时依然走 IDE 里配置的路径。我建议干脆两边都设成同一个值，省得绕弯。
• Distribution 区域可以选择 Wrapper，也可以用 Local installation 直接指定一个手动解压的 Gradle 目录。后者适合你不想经过 wrapper 那一层、强制全局都用同一个 Gradle 版本的场景。多个项目版本不同时不太推荐这么做，除非你有十足的把握。

GUI 和命令行的差异我一直觉得是个信息盲区。很多人只搜到改环境变量，没意识到 AS 自己的设置也会覆盖环境变量。遇到“我明明改了 GRADLE_USER_HOME 为什么还往 C 盘写”这种问题，多半就是 GUI 里那个路径没同步改。

4. 路径、版本、镜像之外：迁移用户目录后最容易翻车的三个细节

改完路径不等于万事大吉。我把这么多年在“改 Gradle 路径”这个操作上见过的翻车现场做了个归类，基本集中在三个问题上。每个都是真实案例，不是网上抄来的。

4.1 坑一：改了环境变量，项目却还在找旧目录里的东西

“我明明改了 GRADLE_USER_HOME，Sync 也成功了，为什么项目构建时还提示找不到某个文件？”

这类问题大概率是下面几个原因之一：

1. 你只改了 GUI 里的 Service directory path，没改系统环境变量，后来用命令行跑 gradlew 时它读的是系统环境变量，两边不一致。解决方案就是把 GUI 和环境变量都指向同一个目录。
2. 项目里有某个 module 的 build.gradle 里用绝对路径引用了旧地址的文件。这种最隐蔽，排查时可以全局搜一下 C:\\Users 或者 C:/Users 关键字，看看有没有哪个脚本写死了旧路径。
3. 曾经把 zip 放在旧路径的哈希目录里，迁移后新目录是空的，构建要重新下载全部依赖。这不是错误，只是第一次会比较慢，别急着认为是配置失败，喝杯水等它跑完。

4.2 坑二：Gradle 版本和 JDK 版本不匹配

改完路径后最常见的 Sync 报错是：

code复制The project's Gradle version 6.7.1 is incompatible with the Gradle JVM version 17

这个热搜词出现在问题列表里一点不意外。Gradle 不是“任意 JDK 都能跑”，不同 Gradle 版本支持的 Java 运行版本有严格上限。我整理了一个简化版兼容表，按常见组合来参考：

如果你接手一个老项目，gradle-wrapper.properties 写着 6.7.1 或 7.0.2，而 Android Studio 的 Gradle JDK 设置里却选了默认的 JBR 17 或 21，Sync 就会直接不认账。解决办法是把 Settings → Build Tools → Gradle → Gradle JDK 切换成 JDK 11。JDK 11 在 Android Studio 的 JDK 下拉列表里一般能找到，如果没有，就点 Add JDK 手动选你本机装过的老 JDK 路径。

为什么我会在这里特意提它？因为“修改 Gradle 路径”时很多人会顺手在 GUI 里动 Gradle 相关设置，不小心把 Gradle JDK 从原来的 JDK 11 换成了新版，反而触发版本不兼容。如果你的项目原来好端端的，只是改了个缓存路径就报这个错，那大概率是 IDE 设置项被连带改了，迁回去就行。

4.3 坑三：用户名带中文或空格，路径本身就埋雷

这也是一个“怪不过 Gradle”的问题。很多 Windows 用户的系统用户名是中文拼音或直接就是中文汉字，导致默认路径变成：

code复制C:\Users\张三\.gradle

Gradle 本身对中文路径的兼容性时好时坏，你在纯 Java 项目里可能感觉不到，但一旦接入 NDK、CMake 或者某些对路径长度和编码敏感的原生库，问题就像地雷一样连环爆。常见报错包括但不限于找不到文件、编码异常、CMake 构建失败。

解决方案只有一个：把 GRADLE_USER_HOME 指向一个纯英文无空格路径，比如 D:\Android\GradleHome\.gradle。如果你项目源码本身也在含中文的路径下，比如 D:\项目\MyApp，那建议把整个工程也迁到英文路径。别嫌麻烦，我见过不止一个团队因为 Windows 用户名是中文，最后花两天时间查一个 NDK 的诡异编译错误，最后发现根因就是路径里有中文。

4.4 下载超时类报错怎么排除

再补一个很多人会问的：如果报错是 Could not install Gradle distribution from ... SocketTimeoutException，到底应该怎么定位？

按下述顺序排查比较高效：

1. 先试普通浏览器访问 distributionUrl，看能否下载。浏览器也下不动，说明网络到目标服务器不通畅，直接上离线包方案或镜像源。
2. 浏览器能下但 Android Studio 下不动，大概率是 AS 或者 Gradle daemon 走的网络设置特殊，检查系统代理设置有没有影响 tool 的网络访问，但这里不展开具体配置，因为不同网络环境差异很大。
3. 如果项目里明明指定的是腾讯云镜像还是超时，先确认 gradle-wrapper.properties 是否被你改对了——很多人改的是 ~/.gradle 下的全局配置，而不是项目里的 wrapper 文件，自然没生效。

这一整套排查思路适用于绝大多数 Gradle 下载网络问题。

5. 我自己的 Gradle 目录规划习惯：从源头避免再次踩坑

有句话说得好，改路径是治标，合理规划目录才是治本。换了那么多台开发机、帮那么多人修过环境之后，我现在的目录规划已经固定下来了，分享给你参考。

我一般会在 D 盘单独划一个 D:\Android 目录，里面分三个部分：

code复制D:\Android\
├── sdk\                # Android SDK
├── GradleHome\.gradle  # Gradle 用户主目录
└── Projects\           # 所有 Android 工程源码

对应的环境变量设置也很固定：

code复制GRADLE_USER_HOME=D:\Android\GradleHome\.gradle
ANDROID_SDK_ROOT=D:\Android\sdk

Android Studio 安装路径我也不会放 C 盘默认位置，而是装到 D:\Android\AndroidStudio。这么做的核心考量是：以后不管是重装系统还是换电脑，只要 D 盘还在，SDK 和 Gradle 缓存都还在，新环境只要装了 AS 并指向这两个目录，首次 Sync 就会快很多，不用再从零下载十几个 G 的工具链。

每次在新机器上初始化环境时，我会照着这个清单过一遍：

1. 先配置好 GRADLE_USER_HOME 环境变量。
2. 安装 Android Studio，启动后到设置里确认 Service directory path 同环境变量一致。
3. 打开任意一个项目，Sync 一次，确认 wrapper/dists 和 caches 在新目录里正常生成。
4. 观察一两天，确认旧 .gradle 目录不再增长后删除备份。

这个流程走完，基本不会再被 Gradle 路径问题折腾。

最后说一个和路径修改配套的小技巧：如果你同时维护多个项目，你会发现每个项目 Sync 时都会检查自己的 Gradle 版本，而 Gradle 不同版本从官网下载又慢又容易超时。除了前面说的离线包方案，最省心的就是让团队统一 Gradle 版本，至少在 gradle-wrapper.properties 里尽量保持一致。版本统一之后，wrapper/dists 里的缓存只需要存一份，也能大幅减少首次拉取新项目的时间。试想一下，你第一次拉一个仓库，结果因为 Gradle 版本和本地不一致，卡在下载上半小时，这种体验真的够让人崩溃的。从这个角度说，弄清楚路径怎么配、缓存怎么迁，不只是 C 盘空间的问题，直接关系到你每天开发的实际手感。