C盘清理攻略：Gradle默认缓存迁移到D盘全流程

上个月我这边C盘又飘红了，用磁盘分析工具扫了一圈，发现罪魁祸首既不是视频缓存也不是微信聊天记录，而是平时完全没在意过的 Gradle 默认缓存目录。看着那 12.7GB 的占用，我一时不知道该夸 Gradle "尽职尽责"，还是该骂它"太能吃"。

其实这个问题的本质很简单：Gradle 默认把缓存放在用户目录下的 .gradle 文件夹里，对 Windows 来说就是 C:\Users\你的用户名\.gradle。这个文件夹会随着你构建次数增加、依赖版本增多、Gradle 发行版切换，像滚雪球一样越滚越大。今天这篇文章就是完整复盘我迁移 Gradle 默认缓存的全过程，包括为什么迁移、迁移前要考虑哪几种方案、每一步的具体操作，以及我在实测中踩过的坑和排查思路。不管你用的是 Android Studio 还是纯命令行 Gradle 构建，这套迁移方法都适用。

1. 为什么不用急着删缓存：先搞清 .gradle 里装了什么

1.1 一个真实的磁盘告急现场

先说我自己遇到的情况。上个月 20 号左右，我在编译一个 Flutter 项目时突然报 "No space left on device"，当时我以为是 Docker 镜像占用太多，手动清了一轮镜像后有所缓解，但两天后问题再次出现。

后来我用了一款叫 WizTree 的磁盘分析工具扫整个 C 盘，结果吓一跳：C:\Users\admin\.gradle 这个目录居然占用了 12.7GB。当时我第一反应是"是不是缓存文件损坏了导致体积异常"，但点进去看了一圈，发现每个子目录都挺正常，就是单纯的东西多。

1.2 Gradle 默认缓存目录的构成

为了说清楚迁移的必要性，先带你看看 .gradle 目录下到底有哪些"大块头"。用 du -sh 或者 Windows 下的文件夹属性查看，一般会看到这几个重点目录：

注意看 wrapper/dists 这一项。如果你同时维护多个项目，A 项目用 Gradle 7.4，B 项目用 Gradle 8.0，C 项目升到了 8.5，那这三个版本的发行版都会被完整保留，每个版本解压后动辄 150MB 起步，再加上下载的 zip 包，几个版本叠加起来就是几个 G。

1.3 判断你是否需要做缓存迁移的三个信号

不是所有人都有必要马上迁移，我结合自身和周边同事的情况总结出三个信号：

1. 系统盘分区较小：如果你的 C 盘只有 120GB 或 256GB，而 .gradle 目录已经超过 8GB，那迟早会出现"磁盘空间不足导致构建失败"的情况。等到报错再处理，还挺被动的。
2. 多项目多版本 Gradle 并行：今天拉一个 Flutter 项目，明天跑一个 Android 原生项目，后天又试一个 Kotlin Multiplatform 库，wrapper/dists 和 caches/modules-2 会急剧膨胀。
3. 你经常切换分支或并行开发多个依赖库：由于不同分支的依赖版本不同，Gradle 会保留所有版本而不是只留下当前分支用到的版本，时间一长重复和冗余会非常明显。

如果你命中了两条以上，这篇文章接下来的内容就很适合你。

2. 动手迁移前，先把这三种方案想清楚

2.1 方案一：环境变量直改 GRADLE_USER_HOME

Gradle 设计上本身就支持通过环境变量运行用户构建目录重定向，这个环境变量叫 GRADLE_USER_HOME。默认情况下它指向 ~/.gradle，你改成其他盘符的目标路径后，所有基于 Gradle 的构建、Android Studio 的 Gradle 同步、命令行中的 gradlew 脚本都会默认使用新路径。

这个方案的好处很明显：

• 全局生效，改一次就能管住本机所有项目，不需要逐个项目改配置。
• 切换成本低，你不需要移动任何文件，只要把旧目录里的内容复制到新路径即可（甚至不复制也没问题，就是第一次构建会比较痛苦）。
• 符合官方预期，很多 CI 机器上就是这么配置的。

它唯一的限制是：如果你用的是旧版 Gradle 工具