Gradle Cache Entries 深度探索

Gradle Cache Entries 深度探索

️ 一、Gradle缓存全景图

1.1 缓存核心定位

Gradle缓存是构建系统的智能存储中枢，通过本地化存储依赖项和任务输出，避免重复下载与编译。其物理位置遵循分层设计：

• 全局缓存（用户级）：

~/.gradle/caches (Linux/macOS) 或 C:Users<用户>.gradlecaches (Windows)

存储所有项目的公共依赖，如第三方库（JAR/AAR）和插件

• 项目缓存（工程级）：

项目根目录下的 .gradle 文件夹

存储专属编译字节码、任务输出快照等临时数据

# 典型缓存目录结构示例

.gradle/

├── caches/ # 核心缓存区

│ ├── modules-2/ # 依赖库存储

│ │ └── files-2.1/ # 按坐标组织的二进制文件

│ ├── jars-3/ # 编译后JAR缓存

│ └── build-cache-1/ # 任务输出缓存

├── daemon/ # 守护进程日志

└── wrapper/ # Gradle分发包校验

1.2 缓存工作原理

graph LR

A[构建启动] --> B{检查输入哈希}

B -- 匹配 --> C[直接读取缓存输出]

B -- 不匹配 --> D[执行任务]

D --> E[存储输出到缓存]

E --> F[标记 FROM-CACHE]

当任务（如 compileJava）执行时，Gradle会计算输入签名（源码+依赖+参数）。若匹配缓存条目，则直接复用历史输出，构建日志显示 :taskName FROM-CACHE。

二、缓存清理实战手册

2.1 清理场景判断

| 场景 | 处理方案 | 风险等级 |

|---------------------|-----------------------------------|----------|

| 依赖版本更新 | 删除特定模块路径 | ⭐ |

| 构建结果异常 | 清除项目级 .gradle 目录 | ⭐⭐ |

| 磁盘空间不足 | 删除全局缓存 | ⭐⭐⭐⭐ |

| 跨项目缓存共享 | 配置远程缓存服务器 | ⭐⭐ |

2.2 四种清理方式

1. 精准手术刀（推荐）

删除特定依赖路径（如 ~/.gradle/caches/modules-2/files-2.1/com/google/gson/）

rm -rf ~/.gradle/caches/modules-2/files-2.1/groupId/artifactId

2. 全局重置

清理整个缓存目录（慎用！）：

// Java实现的缓存清理工具

import java.io.File;

public class CacheCleaner {

public static void main(String[] args) {

File cacheDir = new File(System.getProperty("user.home") + "/.gradle/caches");

if (cacheDir.exists()) {

deleteRecursively(cacheDir); // 递归删除

System.out.println("缓存已清零");

}

}

private static void deleteRecursively(File f) {

if (f.isDirectory()) {

for (File child : f.listFiles()) {

deleteRecursively(child);

}

}

f.delete();

}

}

3. Gradle原生指令

# 清理构建缓存（不包含依赖）

./gradlew cleanBuildCache

# 强制刷新依赖

./gradlew build --refresh-dependencies

4. Android Studio可视化操作

File > Settings > Build Tools > Gradle → 点击 Open in Explorer 手动删除

️ 三、缓存策略高阶配置

3.1 本地缓存优化

// settings.gradle 配置示例

buildCache {

local {

directory = new File(rootDir, 'my-cache') // 自定义缓存路径

removeUnusedEntriesAfterDays = 14 // 自动清理旧条目

targetSizeInMB = 1024 // 最大缓存空间

}

}

3.2 远程缓存架构

graph TD

A[开发者机器] -->|推送/拉取| B(HTTP缓存服务器)

C[CI构建节点] -->|写入| B

D[新开发者] -->|首次拉取| B

优势：团队共享编译结果，新成员首次构建时间减少 70%。

3.2.1 搭建缓存服务器

方案1：HTTP缓存（快速启动）

# 使用Gradle官方节点

java -jar build-cache-node-9.11.jar start 

--data-dir=/cache/storage 

--port=8080

客户端配置：

buildCache {

remote(HttpBuildCache) {

url = 'http://cache-server:8080/cache'

push = isCiBuild // CI机器推送，开发者只拉取

}

}

方案2：AWS S3缓存（企业级）

buildCache {

remote(AmazonS3BuildCache) {

bucket = 'my-company-gradle-cache'

region = 'us-east-1'

accessKey = System.env.AWS_ACCESS_KEY

secretKey = System.env.AWS_SECRET_KEY

}

}

四、缓存异常诊疗室

4.1 典型故障场景

1. 幽灵依赖问题

现象：ClassNotFoundException 但依赖存在

根因：缓存中残留旧版本依赖（如 1.0.0 vs 2.0.0）

方案：

# 精准删除问题模块

rm -rf ~/.gradle/caches/modules-2/files-2.1/group/problem-module

2. 缓存锁死

现象：构建卡在 Resolving dependencies

根因：.gradle/caches 中文件权限错误或进程占用

方案：

# Linux/macOS 修复权限

sudo chmod -R 755 ~/.gradle

# Windows 使用解锁工具

Handle.exe -p gradle

3. 跨版本污染

现象：Gradle升级后构建失败

根因：旧版本缓存格式不兼容

方案：全量清理缓存并重建

4.2 监控与日志

启用缓存调试模式（gradle.properties）：

# 显示缓存命中详情

org.gradle.caching.debug=true

示例输出：

Task :compileJava FROM-CACHE

Cache Key: a8d3e8f7c0b

Origin: Build cache at http://cache-server:8080

五、缓存效能度量

通过Mermaid可视化缓存空间分布：

pie

title 缓存空间占比分析

"依赖库 (JAR/AAR)" : 45

"编译字节码" : 30

"任务输出快照" : 15

"插件资源" : 10

建议定期执行 gradle build --scan 生成构建报告，重点关注 Cache Effectiveness 指标。

总结与最佳实践

::: tabs#summary

@tab 基础规范

• 为CI机器单独配置缓存目录，避免污染开发者环境

• 定期执行 ./gradlew cleanBuildCache 维护缓存健康度

• 使用 --build-cache 参数验证缓存命中效果

@tab 团队协作

• 新成员首次构建时从远程缓存预加载基础依赖

• 在 gradle-wrapper.properties 中固化Gradle版本

• 通过 dependencyUpdates 插件检测依赖更新

@tab 企业级优化

// CI流水线专用配置

boolean isCI = System.getenv('CI') != null

buildCache {

remote(HttpBuildCache) {

url = 'http://company-cache/cache'

push = isCI // 仅CI推送

enabled = true

}

local {

enabled = !isCI // 开发者使用本地缓存

}

}

@tab 未来演进

• 探索分层缓存策略：本地SSD > 局域网缓存 > 云存储

• 集成机器学习预测模型预加载依赖

• 实现增量式缓存签名计算降低CPU开销

:::