Build Cache 构建缓存机制剖析与远程缓存服务架构搭建

Build Cache 的目标是复用任务输出：如果同一段工作在相同输入下已经被执行过，就不要再执行一次。

它和 UP-TO-DATE 的区别在范围。UP-TO-DATE 只复用当前工作区上一次构建的结果；Build Cache 可以从本地缓存目录或远程缓存服务拿到其他工作区、其他 CI job 生产过的输出。

inputs + task implementation + normalized paths
        |
        v
cache key
        |
        +-- hit  -> restore outputs
        `-- miss -> execute task -> store outputs

Cache key 由什么决定

Gradle 会基于任务实现和输入快照计算 key：

Task implementation
Action classpath
Input properties
Input files content
Path sensitivity
Classpath normalization
Gradle/environment relevant state

输出不参与 key，它是 key 对应的值。命中后 Gradle 把缓存中的输出还原到任务输出位置。

这意味着自定义任务必须把所有影响输出的因素声明为输入。漏声明的输入会导致错误命中；多声明无关输入会导致命中率下降。

本地缓存与远程缓存

本地缓存默认位于 Gradle User Home，适合单机复用。远程缓存适合团队和 CI：

// settings.gradle.kts
buildCache {
    local {
        isEnabled = true
    }

    remote<HttpBuildCache> {
        url = uri("https://cache.example.com/cache/")
        isPush = providers.environmentVariable("CI").isPresent
    }
}

常见策略是：

• 开发者可以 pull remote cache，但不 push。
• CI 主分支或可信构建负责 push。
• PR 构建通常只 pull，避免污染缓存。

远程缓存必须被当作供应链基础设施管理。错误产物被 push 后，会影响大量构建。

可缓存任务的条件

一个任务适合缓存，需要满足：

• 输出完全由声明输入决定。
• 不依赖绝对路径或机器本地状态。
• 不读未声明环境变量。
• 不写输出目录以外的文件。
• 输出稳定，不包含随机数、当前时间、临时路径。
• 工具版本和命令参数进入输入。

坏例子：

@TaskAction
fun generate() {
    outputFile.get().asFile.writeText(
        "builtAt=${Instant.now()}\n"
    )
}

这个输出每次都不同。除非 builtAt 是声明输入，否则任务不应该缓存。

Android 工程中的缓存命中难点

Android 构建缓存难点通常不在 Gradle 本身，而在输入稳定性：

• KAPT 生成目录和 processor 行为不稳定。
• 字节码插桩输出带时间戳或绝对路径。
• R8 mapping、资源 ID、Manifest 合并受 variant 输入影响。
• CI workspace 路径不同，任务用了 ABSOLUTE 路径敏感性。
• 依赖解析动态版本导致 classpath 变化。

如果 remote cache 命中率低，不要只调缓存服务器。应先检查任务输入归一化和构建可复现性。

缓存服务架构要点

一个远程缓存服务至少要考虑：

团队早期可以用 Gradle 官方远程缓存方案或兼容 HTTP build cache 的服务。关键不是先自研，而是先把 push 策略和命中率指标管住。

如何判断缓存是否有效

执行：

./gradlew :app:assembleDebug --build-cache --info

关注输出：

• FROM-CACHE：任务输出来自缓存。
• UP-TO-DATE：当前工作区输出已经有效。
• 没有标记：任务执行了。

Build Scan 中可以看到每个任务的 cacheability reason。若任务不可缓存，要看是任务类型未标记，还是输入输出声明不满足要求。

工程风险与观测清单

Build Cache 构建缓存机制剖析与远程缓存服务架构搭建 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。

关键风险矩阵

需要持续观测的指标

• 配置阶段耗时是否随模块数量线性或超线性增长。
• 单次本地 debug 构建的关键路径任务是谁。
• CI clean build 与 incremental build 的耗时差距。
• 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
• Configuration Cache 的命中率和失效原因。
• Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
• 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
• 自定义插件是否提前实现了无关任务。
• 构建日志中是否出现未声明输入、重叠输出、deprecated API。
• 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
• 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
• 变更是否影响开发构建、测试构建和发布构建三条路径。

回滚与降级策略

• 构建逻辑变更与业务代码变更分开提交，便于二分定位。
• Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
• 新插件能力先只接入一个低风险模块，再扩大到全工程。
• 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
• 新增插桩、生成代码、资源处理逻辑必须提供开关。
• 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
• 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
• 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

审计问题

1. 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
2. 它是否读取了没有声明为输入的文件、环境变量或系统属性。
3. 它是否在配置阶段执行了本应放到任务动作里的工作。
4. 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
5. 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
6. 它是否把权限、密钥、签名文件路径写进了仓库。
7. 它是否破坏了并发执行，例如多个任务写同一个目录。
8. 它是否能在失败时输出足够日志，帮助定位根因。
9. 它是否能通过一个开关降级，避免阻塞全工程构建。
10. 它是否有最小复现样例或 TestKit/集成测试覆盖。
11. 它是否会让下游模块承担不必要的依赖或任务成本。
12. 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。

反模式清单

• 用 clean 掩盖输入输出声明错误。
• 用 afterEvaluate 修补本可以用 Provider 表达的依赖关系。
• 用动态版本解决依赖冲突，却让构建不可复现。
• 把所有公共配置塞进一个巨型 convention plugin。
• 在 debug 构建默认开启 release 级别的重型优化。
• 在任务动作里读取 project 或全局 configuration。
• 在多个任务中共享同一个临时目录。
• 缓存命中率异常时只重启 CI，不分析 miss reason。
• 把构建扫描链接当作可选附件，而不是性能回归证据。
• 用本地 IDE 成功运行证明 CI 发布链路安全。

最小实操脚本

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Build Cache 构建缓存机制剖析与远程缓存服务架构搭建 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Build Cache
• Gradle Build Cache Concepts
• Gradle Build Cache Performance