第1章 AGP版本升级的构建依赖变化全景

1.1 为什么AGP版本升级会破坏离线缓存？

在 Android 构建系统中，离线缓存（--offline 模式、Gradle 构建缓存、预置依赖项）是提升 CI/CD 稳定性和开发效率的关键手段。然而，AGP 版本升级通常会引入依赖解析行为的根本性改变，导致精心搭建的离线缓存体系大面积失效。核心原因在于：AGP 7.x 迁往 8.x 的过程中，Gradle 的依赖元数据解读策略、变体选择逻辑以及构件转换（Artifact Transform）注册机制发生了架构级调整，这些调整直接改变了缓存键（Cache Key）的生成算法，使得旧版缓存命中率急剧下降。

1.2 AGP 7.x 与 8.x 依赖解析行为差异

下表是 AGP 7.x 与 8.x 在依赖解析域中的关键差异对比，这些差异直接影响离线缓存的行为和命中率：

1.3 离线缓存失效的根本原因分析

针对 AGP 版本升级造成的缓存失效，可以从以下三个技术层面进行根因挖掘：

• Gradle Module Metadata (GMM) 引入： 当库发布者从 POM 切至 GMM 后，Gradle 会优先消费 GMM，不再使用传统 POM。缓存键从 groupId:artifactId:version:classifier 变为 组:模块:版本:变体:能力列表，这会导致旧版离线包彻底失效。

  // POM 缓存键（AGP 7.x 常见）
  com.google.guava:guava:31.1-jre
  
  // GMM 缓存键（AGP 8.x 默认）
  com.google.guava:guava:31.1-jre:runtimeElements:{"require":"com.google.common"}

• 变体感知缓存机制： AGP 8.x 强制将构建类型（buildType）、产品风味（flavor）以及消费者规则文件（如 consumerProguardFiles）编码入缓存键。在 AGP 7.x 中，只要依赖坐标不变就可以命中离线缓存；到 8.x 后，相同坐标但不同变体也会产生不同的缓存键，从而按需重新拉取依赖。
• Artifact Transform 签名变化： Transform 的 类全名 是缓存键计算的一部分。AGP 升级如果修改了内置 Transform（如 D8 去糖、R8 压缩）的实现类名或输入输出规范，会生成新签名，导致旧版构建缓存失效，进一步影响离线模式下任务执行。

1.4 常用 Gradle 插件版本兼容性参考

离线缓存管理离不开与 AGP 版本相匹配的插件版本。下表是主流插件在 AGP 7.x 和 8.x 中的兼容性对照，错误匹配会直接引起依赖解析失败或缓存异常。

1.5 本章小结

通过本章分析可知，AGP 7.x 到 8.x 的升级绝不仅是一个版本号的变更，它涉及依赖元数据优先级模型、变体感知缓存策略、Artifact Transform 生命周期这三个核心构建子系统的深度重构。离线缓存失效的本质是缓存键生成规则与 Gradle 模块元数据体系的演进产生的代差。

在接下来的章节中，我们将以此为基础，逐步构建一套可以对抗版本升级冲击的离线依赖缓存管理策略，从源头锁定缓存键、显式控制变体解析、并建立自动化兼容性校验系统。