Configuration Cache：跳过配置期的序列化方案与兼容性改造
Configuration Cache 优化的是配置阶段：当同一组任务的构建配置输入没有变化时，Gradle 可以直接复用上次配置阶段的结果，跳过 project/build script/task graph 的重新配置。
它和 Build Cache 存的东西不同。Build Cache 存任务输出，Configuration Cache 存配置阶段计算出的构建模型和任务图。
第一次执行:
init -> configure projects -> calculate task graph -> execute tasks
|
v
store configuration cache
第二次执行:
init -> load task graph from cache -> execute tasks
它为什么难
配置阶段原本允许构建脚本做很多动态事情：读文件、读环境变量、查系统属性、遍历任务、访问 Project。Configuration Cache 要把配置结果序列化下来，就要求这些动态输入可追踪、运行时状态可隔离。
如果构建逻辑在配置期偷偷读取 local.properties、调用 git rev-parse、读取当前时间，Gradle 必须知道这些输入，否则缓存复用就不安全。
常见不兼容写法
任务动作中访问 project：
tasks.register("badTask") {
doLast {
println(project.layout.buildDirectory.get())
}
}
Project 是配置期对象，不应该在执行期闭包中捕获。应改成把需要的值作为 Provider 或 Property 注入任务：
abstract class GoodTask : DefaultTask() {
@get:InputDirectory
abstract val buildDirInput: DirectoryProperty
@TaskAction
fun run() {
println(buildDirInput.get().asFile)
}
}
tasks.register<GoodTask>("goodTask") {
buildDirInput.set(layout.buildDirectory)
}
配置输入要显式建模
读取环境变量：
val apiHost = System.getenv("API_HOST")
应改成：
val apiHost = providers.environmentVariable("API_HOST")
读取 Gradle property：
val channel = providers.gradleProperty("channel")
Provider API 让 Gradle 知道这些值是配置输入，变化时能正确让 configuration cache 失效。
Android 工程的改造顺序
推荐顺序：
- 升级到当前工程可支持的 Gradle 和 AGP。
- 执行
./gradlew :app:assembleDebug --configuration-cache。 - 按报告修复第一批不兼容点。
- 修复自定义插件和 build-logic。
- 对常用任务加入 CI 验证。
- 再扩展到测试、release、发布任务。
不要一开始就要求所有任务全部兼容。先让开发者最高频的 debug build 和 test build 命中，收益最直接。
与 Task Configuration Avoidance 的关系
Task Configuration Avoidance 减少本次配置阶段实际创建的任务；Configuration Cache 让后续构建不再执行配置阶段。
两者关系：
第一次:
少配置任务 -> 更快生成 cache entry
后续:
命中 configuration cache -> 跳过配置阶段
如果构建逻辑仍然 eager realize 大量任务，即使 configuration cache 第一次 miss，也会很慢；如果配置缓存经常 miss，avoidance 仍能兜底降低损耗。
失效不是失败
Configuration Cache 失效有合理场景：
- 构建脚本变化。
- Gradle/AGP/插件版本变化。
- 请求的任务集合变化。
- 配置输入变化，例如 Gradle property、环境变量。
目标不是永远不失效，而是让高频重复构建稳定命中。对于 CI，每个 job 工作区可能是冷启动，configuration cache 的价值取决于是否持久化 Gradle User Home 或复用 workspace。
工程风险与观测清单
Configuration Cache：跳过配置期的序列化方案与兼容性改造 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。
因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。
关键风险矩阵
| 风险点 | 触发条件 | 直接后果 | 观测方式 | 缓解策略 |
|---|---|---|---|---|
| 输入声明缺失 | 构建逻辑读取未声明文件或环境变量 | UP-TO-DATE 或缓存结果错误 | 使用 --info 和 Build Scan 查看输入变化 |
把所有影响输出的状态建模为 @Input 或 Provider |
| 绝对路径泄漏 | 任务 key 包含本机路径 | CI 与本地缓存无法复用 | 对比不同机器的 cache key 变化 | 使用相对路径敏感性和路径归一化 |
| 配置期副作用 | build script 执行 I/O、Git、网络请求 | 任意命令都变慢，configuration cache 失效 | 执行 help --scan 观察配置期耗时 |
把副作用移动到任务动作并声明输入输出 |
| Variant 污染 | 对所有 variant 注册重型任务 | debug 构建被 release 逻辑拖慢 | 查看 realized tasks 和 task timeline | 使用 selector 精确匹配目标 variant |
| 权限外溢 | 插件或脚本读取 CI secret、用户目录 | 构建不可复现，存在供应链风险 | 审计构建日志和环境变量访问 | 使用最小权限和显式 secret 注入 |
| 并发竞争 | 多个任务写同一输出目录 | 产物互相覆盖或偶发失败 | 检查 overlapping outputs 报告 | 每个任务拥有独立输出目录 |
| 缓存污染 | 不可信分支向远程缓存 push | 全团队复用错误产物 | 统计 remote cache push 来源 | 只允许受信任 CI 写入远程缓存 |
| 回滚困难 | 构建逻辑与业务变更混在一起 | 发布失败时无法快速定位 | 变更审计和构建 scan 对比 | 构建逻辑独立提交、独立验证 |
| 降级缺口 | 新 Gradle/AGP API 无兜底策略 | 升级失败后阻塞全线开发 | 记录兼容矩阵和失败任务 | 保留可回滚版本和迁移开关 |
| 资源释放遗漏 | 自定义任务打开文件句柄或进程未关闭 | Windows/CI 上清理失败或锁文件 | 观察 daemon 日志和文件锁错误 | 使用 Worker API 或 try/finally 释放资源 |
需要持续观测的指标
- 配置阶段耗时是否随模块数量线性或超线性增长。
- 单次本地 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 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
- 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。
最小验证矩阵
| 验证场景 | 命令或动作 | 期望信号 |
|---|---|---|
| 空任务配置成本 | ./gradlew help --scan |
配置期没有无关重任务 |
| 本地增量构建 | 连续执行同一 assemble 任务 | 第二次大量任务 UP-TO-DATE |
| 缓存复用 | 清理输出后启用 build cache | 可缓存任务出现 FROM-CACHE |
| Variant 隔离 | 分别构建 debug/release | 只出现目标 variant 相关任务 |
| CI 可复现 | 干净工作区执行 release 构建 | 不依赖本机隐藏文件 |
| 依赖稳定 | 执行 dependencyInsight | 版本选择可解释，无动态漂移 |
| 配置缓存 | --configuration-cache 连跑两次 |
第二次复用配置缓存 |
| 发布审计 | 记录 scan、mapping、签名信息 | 产物可追溯、可回滚 |
审计问题
- 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
- 它是否读取了没有声明为输入的文件、环境变量或系统属性。
- 它是否在配置阶段执行了本应放到任务动作里的工作。
- 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
- 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
- 它是否把权限、密钥、签名文件路径写进了仓库。
- 它是否破坏了并发执行，例如多个任务写同一个目录。
- 它是否能在失败时输出足够日志，帮助定位根因。
- 它是否能通过一个开关降级，避免阻塞全工程构建。
- 它是否有最小复现样例或 TestKit/集成测试覆盖。
- 它是否会让下游模块承担不必要的依赖或任务成本。
- 它是否能在升级 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
这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Configuration Cache：跳过配置期的序列化方案与兼容性改造 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。