第1章：Gradle缓存同步概述

1.1 什么是Gradle缓存同步

Gradle缓存同步是指在多个构建环境（开发者本地机器、CI/CD代理节点、Docker容器）之间，共享和同步构建缓存（任务输出、中间产物、依赖解析结果）的机制与实践。其核心目标是确保一次计算的结果可以被可靠地复用，从而避免重复构建。

缓存同步涉及两个关键组件：

• 本地缓存： 位于 $HOME/.gradle/caches 下的本地文件系统存储，用于开发阶段的快速命中。
• 远程缓存： 一个集中式的HTTP服务（如使用Gradle Enterprise、Artifactory或自建服务），用于跨机器共享缓存条目。

1.2 核心价值与驱动力

在大型项目中，Gradle缓存同步是加速构建的关键手段。下表展示了其核心价值指标：

维度	未使用缓存同步	使用缓存同步	典型提升
CI全量构建	40 分钟	4 分钟（依赖命中）	10x
开发者首次构建	30 分钟	2 分钟（拉取远程缓存）	15x
CI代理开销	100% 计算量	30% 计算量	70% 成本节省
跨分支构建	完全重复构建	共享不变模块产物	差异构建

1.3 适用大规模项目场景

以下场景强烈建议实施Gradle缓存同步：

1. 多模块单体仓库（Monorepo）： 模块之间依赖复杂，单次提交可能只修改一个模块，但全量构建代价巨大。
2. 无状态CI代理： 容器化或临时虚拟机环境，每次构建都是全新环境，本地缓存为空。
3. 高频合并代码： 多个功能分支并行开发，频繁向主分支合并，需要快速验证基础模块。
4. 跨团队依赖： 基础库（如内部框架、工具库）由不同团队维护，构建产物需要快速分发。
5. 严格的构建验收要求： 每个提交都需要通过构建验证，缩短反馈周期。

1.4 与增量构建的关系

增量构建和缓存同步是互补的关系，而不是替代关系：

• 增量构建（Incremental Build）： 基于文件时间戳和任务输入/输出声明，在单机上判断任务是否为UP-TO-DATE。这是Gradle内置的优化机制。
• 缓存同步（Cache Sync）： 将构建缓存从一台机器分发到另一台机器。它基于缓存键（CacheKey）在分布式环境中实现全局的UP-TO-DATE判断。

当一个缓存条目在远程缓存中存在时，CI代理会直接下载并解压到本地构建目录，跳过任务执行阶段，这一点与增量构建的最终效果一致，但范围扩大到了整个集群。

1.5 缓存同步核心流程

下面这张流程图展示了从代码提交到缓存命中的完整同步路径：

流程图清晰地展示了两种路径：缓存命中路径（3->6）直接从本地缓存输出产物，速度最快；缓存未命中路径（3->4->5->6）则触发远程同步请求，将远程存储中的产物拉取到本地并输出。

1.6 启用远程缓存的基本配置

在大型项目中启用远程缓存非常简单，通常只需要在项目根目录下的settings.gradle.kts中添加如下配置：

// settings.gradle.kts
buildCache {
    local {
        isEnabled = true
        directory = File(rootDir, ".gradle-cache-local")
        // 限制本地缓存大小与保留策略
        removeUnusedEntriesAfterDays = 7
    }
    remote<HttpBuildCache> {
        url = uri("https://build-cache.your-company.com/cache/")
        isEnabled = true
        // 在CI/CD环境中开启推送权限，开发者机器通常只读取
        isPush = System.getenv("CI") != null
        // 配置基本身份验证
        credentials {
            username = System.getenv("CACHE_USERNAME") ?: ""
            password = System.getenv("CACHE_PASSWORD") ?: ""
        }
    }
}

同时，在gradle.properties中开启缓存开关：

# gradle.properties
org.gradle.caching=true
# 开启调试日志以分析缓存命中/未命中原因
org.gradle.caching.debug=true