1. AGP升级背景与缓存隔离必要性：Gradle版本变更、构建缓存失效风险、模块间依赖冲突

Android Gradle Plugin（AGP）每次大版本升级都伴随着 Gradle 版本基线跃迁、构建缓存策略调整和模块间依赖契约变化。在大型多模块工程中，这些变更的叠加效应往往导致构建缓存大面积失效、模块依赖冲突频发，进而引发编译失败或增量构建性能滑坡。本章从版本联动关系、缓存失效机制和依赖冲突模式三个维度剖析问题根源，并引出模块边界缓存隔离方案的核心价值。

1.1 AGP 版本演进与 Gradle 版本绑定

AGP 与 Gradle 之间存在严格的版本兼容性矩阵。每次 AGP 升级都要求同步升级 Gradle 版本，这一联动关系直接决定了构建缓存的键空间和序列化格式是否发生变化。

在升级过程中，build.gradle 中的 AGP 依赖声明和 gradle-wrapper.properties 中的 Gradle 发行版 URL 必须同步修改：

// build.gradle — AGP 版本变更示例
buildscript {
    dependencies {
        // AGP 7.4.2 → 8.2.2
        classpath 'com.android.tools.build:gradle:8.2.2'
    }
}

# gradle-wrapper.properties — Gradle 版本同步升级
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

1.2 构建缓存失效的三大风险场景

AGP 升级过程中，构建缓存失效并非偶然事件，而是由以下三类确定性风险驱动：

缓存失效的直接后果是增量构建退化为全量构建，大型工程（500+ 模块）的构建耗时从数分钟激增至数十分钟。缓存隔离方案正是为了在这些风险场景中为每个模块提供独立的缓存保护域。

# 构建缓存配置 — gradle.properties
org.gradle.caching=true
org.gradle.caching.debug=false
org.gradle.caching.local.enabled=true
org.gradle.caching.local.directory=${projectDir}/.gradle/build-cache

1.3 模块间依赖冲突的典型模式

在多模块工程中，AGP 升级还会通过依赖传递机制诱发以下三类冲突：

• 多模块 AGP 版本不一致：子模块通过 buildscript 或 plugins 块引入不同版本的 AGP 插件，导致构建图解析失败。
• 依赖传递路径冲突：两个模块通过不同传递路径引入同一个第三方库的不同版本，Gradle 的版本裁决机制可能选中不兼容版本。
• API 兼容性断裂：新 AGP 版本废弃或修改了特定 API（如 Transform API 迁移到 Instrumentation API），依赖旧 API 的模块编译失败。

# 依赖冲突典型日志摘录
> Could not resolve all dependencies for configuration ':module-a:releaseRuntimeClasspath'.
> Conflict found: dependency 'com.example:lib-core' version 2.0.0 (required by :module-b) vs 1.8.0 (required by :module-c)

1.4 缓存隔离方案的核心价值

模块边界缓存隔离方案的核心思路是：在每个模块的构建缓存边界上建立独立的缓存域，从根源上隔离 AGP/Gradle 版本变更带来的缓存污染与依赖冲突。该方案包含三大设计原则：

• 缓存域自治：每个模块拥有独立的缓存键空间和存储目录，模块间缓存互不干扰。
• 边界可观测：缓存命中/未命中、缓存读写延迟、缓存空间占用等指标在模块维度可采集、可监控。
• 升级可适配：缓存隔离层封装版本差异，AGP 升级时只需调整隔离层适配器，无需侵入模块业务代码。