Gradle 依赖反复下载？缓存回收与排查指南

背景#

不少 Android / Java 开发者遇到过这个现象：一个 Gradle 项目，之前正常打开过、依赖都下载好了，过了一两周甚至一个月重新打开 Android Studio 或者执行 ./gradlew build，Gradle 又开始从头下载所有依赖了。

这不是错觉，也不是 Gradle 的 bug。背后有几层原因，下面逐个拆解。

原因一：Gradle 缓存 GC（最常见）#

Gradle 内置了缓存自动清理机制。默认每 7 天 检查一次，删除 24 小时内未被访问 的缓存条目。

也就是说，如果你两周没碰项目，Gradle Daemon 也没运行，那么整个 ~/.gradle/caches/modules-2/ 里的依赖 Jar 包都会被判定为”已过期”，在下次构建时被当作无效缓存清理掉。下次构建就只能全部重下。

1
cat ~/.gradle/caches/gc.properties

1
# 方案 A：完全禁用缓存 GC（推荐）
2
gradle.cache.cleanup.enabled=false
3

4
# 方案 B：延长保留天数
5
gradle.cache.cleanup.retain.unused.days=30

原因二：Gradle Wrapper 版本变化#

现在很多项目通过 Gradle Wrapper 锁版本。但如果：

• 项目接入了 Renovate / Dependabot 自动更新 Wrapper 版本
• 同事提交了升级 Wrapper 的 commit（./gradlew wrapper --gradle-version=8.x）
• 之前是 8.7，后来自动升级到了 8.9

那整个 Gradle 发行版都要重新下载，而且新版本 Gradle 的缓存路径不同，已有的 ~/.gradle/caches/ 对不上，就相当于所有依赖也要重新解析和下载。

1
cat gradle/wrapper/gradle-wrapper.properties

1
./gradlew wrapper --gradle-version=8.7

原因三：~/.gradle 目录被系统清理#

Arch Linux（或者用 systemd-tmpfiles 的发行版）每天会按策略清理用户缓存目录。

检查自己的环境：

1
cat ~/.gradle/caches/gc.properties 2>/dev/null || echo "文件不存在（GC 未触发，但可以看 modules-2 体积判断）"
2
du -sh ~/.gradle/caches/modules-2/

如果 modules-2/ 的大小从几个 GB 变成了几十 MB，那肯定是被清理过了。

排查是否被 tmpfiles 清理：

1
grep -r "gradle" /usr/lib/tmpfiles.d/ /etc/tmpfiles.d/

如果确实有相关配置，可以在 ~/.config/systemd/user/tmpfiles.d/ 里覆盖。不过更多情况下这只是人为误操作（比如清理磁盘时删了 ~/.gradle）。

原因四：依赖元数据过期#

Gradle 在判断依赖是否需要重新下载时，会对比 Maven 仓库返回的 POM / module 文件的 Last-Modified 时间戳。如果远端仓库返回了比本地缓存更新的时间戳（即使内容没变），Gradle 也会认为缓存失效，触发重新下载。

这在用自建 Maven 仓库（如 Nexus、Artifactory）时比较常见，因为某些配置不当的代理仓库会对所有请求都返回最新的时间戳。

1
./gradlew build --info 2>&1 | grep -i "caching\|downloading\|expired"

完整排查流程#

1
# 1. 确认缓存目录现状
2
du -sh ~/.gradle/caches/modules-2/
3

4
# 2. 查看 GC 日志（如果文件不存在说明 GC 从未触发过）
5
cat ~/.gradle/caches/gc.properties 2>/dev/null || echo "文件不存在，GC 尚未触发"
6

7
# 3. 检查 GRADLE_USER_HOME 是否被 IDE 改变
8
echo $GRADLE_USER_HOME
9

10
# 4. 看 Wrapper 版本有没有变过
11
git diff HEAD -- gradle/wrapper/gradle-wrapper.properties
12

13
# 5. 运行一次构建并查看缓存命中情况
14
./gradlew dependencies --console=verbose

总结#

大部分情况下，在 gradle.properties 加上 gradle.cache.cleanup.enabled=false 就能解决问题。如果不想全局关闭 GC，设置 gradle.cache.cleanup.retain.unused.days=30 给一个更长的保留窗口也是个折中的选择。