增量构建的底层机制：Input/Output 检测与 UP-TO-DATE 原理

增量构建的核心不是“Gradle 比较文件时间戳”，而是 Gradle 基于任务声明的输入、输出和归一化规则，判断某个工作节点的结果是否仍然可信。

当一个任务显示 UP-TO-DATE，含义不是“这个任务没有运行过”，而是“在 Gradle 能观察到的输入范围内，重新执行不会产生不同输出”。这句话里的限定非常重要：如果任务偷偷读取了未声明输入，Gradle 就会做出错误判断。

可以把增量构建想象成厨房备餐。厨师不是每次都重做所有菜，而是检查食材、菜谱和成品是否变化。问题在于，如果有人偷偷换了调料瓶但没有登记，厨师看清单会以为一切没变，最终端出的菜就可能不对。

UP-TO-DATE 的判定模型

一个可增量判断的任务至少需要输出。Gradle 会记录上一次执行时的任务快照：

Task Snapshot
├── implementation identity
├── action classpath
├── input properties
├── input files snapshot
├── output files snapshot
└── normalization strategy

下一次构建时，Gradle 重新采集这些信息并比较：

当前快照 == 历史快照
  |
  +-- true  -> UP-TO-DATE，跳过 TaskAction
  `-- false -> 执行任务，更新快照

所以任务类实现本身变化、输入属性变化、输入文件内容变化、输出文件丢失，都可能让任务重新执行。

输入输出注解是契约

自定义任务必须把会影响输出的东西声明出来：

abstract class MinifyTextTask : DefaultTask() {
    @get:InputFile
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val sourceFile: RegularFileProperty

    @get:Input
    abstract val removeBlankLines: Property<Boolean>

    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun minify() {
        val lines = sourceFile.get().asFile.readLines()
        val result = if (removeBlankLines.get()) {
            lines.filter { it.isNotBlank() }
        } else {
            lines
        }
        outputFile.get().asFile.writeText(result.joinToString("\n"))
    }
}

这里有三个关键信息：

• sourceFile 的内容会影响输出。
• removeBlankLines 这个配置参数会影响输出。
• outputFile 是任务产生的结果。

如果漏掉 removeBlankLines，切换配置后任务可能仍然被判定为 UP-TO-DATE。这就是很多“清理一下 build 目录就好了”的根源：不是 Gradle 玄学，而是任务契约不完整。

路径敏感性决定快照稳定性

文件输入不仅要声明“哪个文件”，还要声明路径如何参与比较：

Android/CI 场景下应尽量避免绝对路径进入任务 key。否则同一份源码在 /Users/a/project 和 /home/ci/project 会被视为不同输入，远程缓存命中率会很差。

增量执行与跳过执行不是一回事

UP-TO-DATE 是整个任务跳过。增量执行是任务需要运行，但只处理变化的那部分输入。

abstract class IndexSourcesTask : DefaultTask() {
    @get:Incremental
    @get:InputDirectory
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val sourceDir: DirectoryProperty

    @get:OutputDirectory
    abstract val indexDir: DirectoryProperty

    @TaskAction
    fun index(inputChanges: InputChanges) {
        inputChanges.getFileChanges(sourceDir).forEach { change ->
            when (change.changeType) {
                ChangeType.ADDED,
                ChangeType.MODIFIED -> rebuildOneIndex(change.file)
                ChangeType.REMOVED -> removeOneIndex(change.normalizedPath)
            }
        }
    }
}

流程是：

输入完全没变
  -> UP-TO-DATE，任务动作不执行

输入部分变化
  -> 执行 TaskAction
  -> InputChanges 告诉任务哪些文件 added/modified/removed

这就是为什么编译器、资源处理器、索引生成器会特别关注文件级变化。全量任务每次吞整个目录，增量任务只处理差异。

Build Cache 比 UP-TO-DATE 更进一步

UP-TO-DATE 比较的是同一工作区的历史快照。Build Cache 则把任务输出按 cache key 存起来，让另一个工作区也能复用。

Developer A
  inputs hash -> cache key -> outputs pushed

CI / Developer B
  same inputs hash -> same cache key -> outputs downloaded

要让任务可缓存，除了输入输出完整，还要满足：

• 输出只由声明输入决定。
• 不依赖工作区绝对路径。
• 不读取未声明环境状态。
• 不写输出目录之外的文件。
• 工具版本、编译器参数等也进入输入。

这也是为什么“能 UP-TO-DATE”不等于“适合远程缓存”。远程缓存把错误扩大到整个团队，契约必须更严格。

Android 构建中的增量敏感点

Android 工程常见的增量破坏点包括：

• 注解处理器不是增量处理器，导致 Kotlin/Java 编译重跑范围扩大。
• 自定义 Gradle task 未声明完整输入输出。
• 资源常量或跨模块 R 引用扩大编译影响范围。
• build script 配置期读取动态文件，让 configuration cache 失效。
• 字节码插桩工具输出不稳定，每次生成不同 class。

AGP 近年来推动非传递 R、非 final R、per-class dexing、KSP、configuration cache，本质上都在缩小“一个变化会污染多大构建子图”。

诊断增量问题

定位某个任务为什么重跑，优先使用：

./gradlew :app:compileDebugKotlin --info
./gradlew :app:assembleDebug --scan

观察点：

• 任务是否显示 UP-TO-DATE、FROM-CACHE、NO-SOURCE。
• --info 中是否说明某个输入属性变化。
• Build Scan 的 timeline 中哪个任务耗时异常。
• 自定义任务是否有未声明输入或输出。

如果一个任务“每次都跑”，不要先怪 Gradle。先问：这个任务是否真的给了 Gradle 足够的信息来判断它可以不跑？

工程风险与观测清单

增量构建的底层机制：Input/Output 检测与 UP-TO-DATE 原理 一旦进入真实 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

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 增量构建的底层机制：Input/Output 检测与 UP-TO-DATE 原理 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Incremental Build
• Gradle Build Cache
• Android Optimize Build Speed