第1章 AGP版本升级场景与缓存一致性挑战
版本差异 · 缓存格式变化 · 增量构建失效

1.1 适用场景

• 跨大版本升级：AGP 从 7.x 升级至 8.x，或从 4.x 直接升至 7.x，缓存格式可能发生不可逆变化。
• 快速迭代团队：项目需在升级后保持增量构建效率，不允许因缓存失效导致全量编译。
• 多分支并行开发：不同分支使用不同 AGP 版本，缓存交叉命中引发状态污染。
• CI/CD 持续集成环境：构建机缓存池需统一管理，升级过程中需保证缓存一致性。

1.2 前置条件

1. 已明确当前 AGP 版本与目标升级版本（例：7.4.2 → 8.2.0）。
2. 备份当前项目的 build 目录及 Gradle 缓存目录（~/.gradle/caches）。
3. 记录升级前增量构建平均耗时，作为验收基准。
4. 确认项目使用的 Gradle 版本与目标 AGP 兼容（参考官方兼容性矩阵）。

1.3 操作步骤

1. 识别版本差异——对比新旧 AGP 的 API 变更、DSL 废弃项、构建配置兼容性。
2. 分析缓存格式变化——查阅 AGP 发行说明，定位缓存（构建缓存、任务输出缓存、资源缓存）的序列化格式或键生成规则是否有变。
3. 评估增量构建失效风险——检查任务依赖图、输入属性快照、文件级增量标记的差异。
4. 标记风险缓存模块——按高风险（全量失效）、中风险（部分失效）、低风险（不影响）分级。
5. 制定缓存清理/迁移策略——确定升级后需强制清除的缓存路径，并写入 gradle.properties 或 CI 脚本。

1.4 输入输出物

类别	输入物	输出物
版本信息	当前 AGP 版本、目标 AGP 版本、Gradle 版本	版本差异对比表
缓存状态	~/.gradle/caches 目录结构、build-cache 快照	缓存格式变化分析报告
构建性能	升级前增量构建时间、任务执行日志	增量构建失效风险评估表
策略文档	官方迁移指南、社区最佳实践	缓存清理/迁移操作工单

1.5 责任边界

• 构建团队：负责版本差异分析、缓存格式变化识别、制定清理策略。
• 开发团队：配合升级后首轮构建验证，报告增量失效情况。
• CI 运维：执行缓存目录清理脚本，监控构建机缓存命中率。
• QA 团队：验收升级后构建输出的正确性，确认无缓存污染导致的编译错误。

1.6 记录材料

• 版本差异对比表（建议 JSON 格式归档至项目 docs/ 目录）。
• 缓存格式变化分析报告（包含受影响的任务类型、缓存键变化示例）。
• 增量构建失效风险评级矩阵。
• 升级操作日志（含执行时间、执行人、回退记录）。

1.7 异常处理

异常场景	现象	处理措施
缓存污染	构建产物类文件缺失或签名错误	立即清除 build 目录及 Gradle 缓存，触发全量构建
增量构建完全失效	每次构建均为全量，耗时增长 300%+	回退至旧 AGP 版本，关闭 ConfigurationCache 后分步升级
缓存兼容性警告	Gradle 输出 Cache entry was written by a different version of the plugin	删除对应缓存子目录，或设置 buildCache.allowInconsistentEntries=false
AGP 与 Gradle 版本不兼容	构建脚本解析报错	参考官方兼容性表升级 Gradle 版本，重新生成缓存

1.8 验收标准

• 增量构建正确性：连续两次无代码变更的构建，输出产物哈希完全一致。
• 缓存命中率：升级后首次构建后，第二次增量构建的任务缓存命中率 ≥ 90%（以 --info 日志为准）。
• 构建时间：升级后增量构建耗时不超过升级前基准值的 120%。
• 无缓存污染：随机抽查 5 个 APK/AAB，安装后功能正常，无类文件缺失或资源错乱。