第2章 缓存目录结构解析：从根路径到版本存储
在进行 Gradle 缓存故障排查时，第一步不是直接删除文件，而是准确理解缓存目录的组成规则。很多开发者因暴力删除整个 ~/.gradle 目录导致构建回退、跨项目共享缓存丢失，甚至 CI 环境反复下载依赖。本章围绕“现象识别 → 数据采集 → 原因定位 → 修复动作 → 复测 → 预防”的排查链路，系统解析 Gradle 缓存根路径、caches 目录层级、模块版本存储规则以及清理风险的判断标准。
排查前置认知：Gradle 缓存是分级结构，不同层级的清理后果差异极大。误删顶层目录可能触发全量重下载，而正确清理模块级缓存则可精确释放空间或修复损坏。
现象识别：四种典型的目录异常表现
在排查开始时，先对照以下四类高发现象，判断是否与缓存目录结构相关：
- 构建失败且日志中出现 “Cached resource not found” — 模块版本目录被误删或损坏。
- 跨项目共享模块无法复用缓存 — 不同项目依赖同一版本，但各自重新下载，说明公共缓存路径未生效或独立项目缓存配置异常。
- 磁盘空间快速增长但
caches/modules-2/files-2.1中无明显大文件 — 怀疑.gradle/7.6等版本隔离目录下残留了旧 Gradle 发行版缓存。 - 删除整个
~/.gradle/caches后构建时间恢复正常但首次构建极慢 — 表明清理动作过广，丢失了可复用的元数据和工件索引。
数据采集：定位缓存根路径与目录清单
执行以下命令快速采集当前环境缓存根路径和目录层级：
# 查看 Gradle 用户主目录（默认缓存根路径）
gradle --version | head -5
# 列出 caches 目录前三级结构（Linux/macOS）
ls -la ~/.gradle/caches/
# 查看当前项目使用的 Gradle 版本隔离目录
find ~/.gradle/caches/ -maxdepth 1 -type d -name "*-*" | sort数据采集要点：
- 默认缓存根路径：
~/.gradle（Windows 为%USERPROFILE%\.gradle）。 - 如果设置了
GRADLE_USER_HOME环境变量，则缓存根路径为该变量值。 - CI/CD 场景下可能将
GRADLE_USER_HOME指向共享存储卷。
原因定位：核心目录层级与模块版本存储规则
以下故障树展示从缓存根路径到具体版本文件的层级关系，以及每个层级的清理风险等级。
核心目录层级解析
Gradle 缓存目录遵循三层存储规则，理解此规则是精准排查的基础。
| 层级 | 目录结构 | 存储内容 | 排查价值 |
|---|---|---|---|
| L1 根 | ~/.gradle/caches/ | 所有缓存根容器 | 总空间占用、是否被误删 |
| L2 子域 | modules-2/ | 模块工件（jar/aar/pom） | 模块级构建故障的直接定位点 |
| L3 版本 | files-2.1/ | 按 group:module:version/ 组织的实际文件 | 单个版本异常的精确操作位置 |
| L2 隔离 | gradle-7.6/ | 特定 Gradle 发行版缓存 | Gradle 版本升级/降级后的残留排查 |
实战技巧：在排查模块下载/解析故障时，优先检查
modules-2/files-2.1/ 下对应模块的 metadata 目录。如果存在 *.module 文件但缺失 *.jar，说明模块缓存损坏，需要精确删除该模块版本目录而非整个 caches。
修复动作：基于风险等级的安全清理方案
根据故障树节点，选择对应的清理粒度。以下判断规则直接决定修复动作的范围。
| 风险等级 | 清理区域 | 建议命令（Linux/macOS） | 影响范围 |
|---|---|---|---|
| 🔴 高 | 整个 caches/ | rm -rf ~/.gradle/caches/ | 所有项目的所有缓存和模块索引将丢失，首次构建极慢 |
| 🟡 中 | modules-2/ | rm -rf ~/.gradle/caches/modules-2/ | 失去所有模块工件，但保留 Gradle 发行版缓存 |
| 🟢 低 | files-2.1 下某模块 | rm -rf ~/.gradle/caches/modules-2/files-2.1/com.example.lib/ | 仅影响该模块，重新构建时自动下载 |
| 🟡 中 | 版本隔离目录 | rm -rf ~/.gradle/caches/7.6/ | 影响该 Gradle 版本的分发缓存，不影响模块工件 |
严重警告：在生产 CI 或多人协作环境中，不要执行
rm -rf ~/.gradle/！这会删除 gradle.properties、caches、wrapper 目录以及 daemon 线程和 native 原生库缓存，导致全量重建甚至认证信息丢失。
复测：验证清理后目录结构与构建行为
清理后必须按以下步骤确认修复结果，并判断是否需要进一步调整。
- 检查目录是否存在且层级正确：执行
ls -la ~/.gradle/caches/modules-2/files-2.1/，确认目标模块版本已移除，且父目录未异常锁定。 - 执行一次构建并观察下载行为：运行
./gradlew build --info 2>&1 | grep -E 'Downloading|Using cached'，确认只重新下载被清理的模块，而非全量重载。 - 验证共享缓存是否仍在：切换另一个依赖相同模块的项目，执行
./gradlew :dependencies --configuration compileClasspath，确认输出中模块来源为file:~/.gradle/caches/而非远程仓库。 - 检查磁盘空间：使用
du -sh ~/.gradle/caches/对比清理前后的差值，确认释放了预期空间。
复测黄金指标：如果清理后构建时间增量 < 被清理模块在远程仓库下载耗时的总合，说明清理范围正确；否则说明误删了过多共享缓存，需缩小清理粒度。
预防：建立缓存目录结构监控与保护机制
为避免反复出现目录结构异常或意外全量清理，建议团队实施以下预防措施。
- 关键目录挂载点备份：在 CI 环境中，将
~/.gradle/caches/modules-2/files-2.1/的每日快照上传至持久化存储，避免因容器重建丢失所有模块缓存。 - 使用 Gradle 内置缓存清理策略：在
gradle.properties中设置org.gradle.cache.cleanup=true以及org.gradle.cache.cleanup.maxDays=30，让 Gradle 自动按最后使用时间（LRT）清理旧模块，避免手动干预。 - 记录目录结构基线：在项目 wiki 中维护一份“目录结构说明表”，包含缓存根路径、重要子目录、版本存储规则，确保团队所有成员知晓哪个目录可以安全清理。
- 目录变更审计：在 CI 流水线中加入以下命令，当
caches/目录结构异常时触发告警：
# 检测 modules-2 目录是否被整体删除
if [ ! -d "$GRADLE_USER_HOME/caches/modules-2" ]; then
echo "[WARN] modules-2 目录缺失，缓存可能被意外全量清理"
exit 1
fi
长期最佳实践：为每个项目独立配置
GRADLE_USER_HOME（指向项目级 .gradle/），配合 CI 的缓存挂载策略，使“模块版本存储规则”完全由项目控制，避免跨项目污染。执行 export GRADLE_USER_HOME=$(pwd)/.gradle-ci 可快速切换。