增量编译原理：Gradle的增量编译机制
说实话，我刚接触 Gradle 的时候，最困惑的就是「我明明只改了一行代码，为啥要重新编译整个项目？」。后来我花了好几天研究官方的文档和源码，才搞明白增量编译到底在做什么。
说白了，增量编译就是 只重新编译那些真正发生了变更的文件，而不是把所有源文件从头到尾再撸一遍。Gradle 能做到这一点，靠的是它内部的一套「快照比对」机制。
Gradle 的核心思路
每个 Task 都有输入（inputs）和输出（outputs）。Gradle 会在 Task 执行前，给 inputs 的所有文件打一个 哈希摘要（比如 MD5），存入构建缓存。下次执行时，它重新计算 inputs 的哈希值，跟上次的对比——如果完全一致，就直接跳过 Task；一旦有变化，才会重新执行。
举个例子：我负责的某个项目里有一个 compileDebugKotlin 任务。每次改一个 .kt 文件，Gradle 并不会把几百个 .kt 全部重新编译，而是只编译那 1 个。这就是增量编译直白的表现。
关键概念：Gradle 的增量机制其实分为两层：Task 级的 up-to-date 检查和文件级的增量编译。前者由 Gradle 核心框架负责，后者由各种插件（如 Kotlin 编译器）自己实现。
Task 的 up-to-date 检查流程
我习惯把这条流程画成一个图，看一眼就清楚了：
Inputs 和 Outputs 的声明方式
要让 Gradle 识别增量，你需要在自定义 Task 里正确声明 inputs 和 outputs。记住三个注解就够了：
@InputFile或@InputFiles—— 标记输入文件/目录@OutputDirectory或@OutputFile—— 标记输出目录/文件@Input—— 标记字符串、整数等非文件输入（比如编译参数）
// 一个简易的增量编译 Task 示例
abstract class MyTransformTask extends DefaultTask {
@InputFiles
abstract ConfigurableFileCollection getInputFiles()
@OutputDirectory
abstract DirectoryProperty getOutputDir()
@Input
abstract Property<String> getTransformVersion()
@TaskAction
void doTransform() {
// 只有 inputs 变化时才会进入这里
println("执行转换逻辑...")
}
}我曾经看到有同事在 Task 里只标记了 outputs，却忘了标记 inputs。结果每次构建 outputs 目录已经存在，Gradle 就认为 up-to-date，再也不执行了——即使源文件都删光了也不报错。嗯，这个坑希望大家别踩。
增量编译的常见陷阱
| 现象 | 根本原因 | 我当时的排查方式 |
|---|---|---|
| 改了文件但 Task 没重新执行 | inputs 声明不完整，漏了关键文件 | 用 --info 日志看 "CACHED" 还是 "EXECUTED" |
| 每次完全重编译，没增量 | 某个 @Input 属性每次构建都变化（如时间戳） | 用 gradle clean 后对比两次 inputs 哈希值 |
| 增量编译偶尔失败，报 ClassNotFoundException | 增量编译导致类文件新旧混合版本冲突 | 临时关闭增量：设置 org.gradle.parallel=false 或清缓存 |
调试小技巧：运行 gradle taskName --info，你会看到类似：
Task ':compileKotlin' is UP-TO-DATE 或 Task ':compileKotlin' is EXECUTED。
如果看到 "CACHED" 但实际文件变了，十有八九是 inputs 声明漏了。
文件级增量：Kotlin 和 Java 编译器的差异
Gradle 的 Task 级 up-to-date 只是第一道防线。真正的文件级增量编译是由编译器插件自己做的。拿 Kotlin 来说，它的 compileKotlin 任务支持 Kotlin 增量编译：它会记录每个 .kt 文件编译后生成的 .class 文件列表，下次只重新编译改了的那几个文件。而 Java 编译器的增量能力相对弱一些，遇到大项目时经常退化成全量编译。
我记得在维护一个几百个模块的安卓项目时，Java 增量编译几乎是无效的。后来我们统一改成 Java 11 + 新的 --release 参数，才好转了一点。
警告：如果开启了 org.gradle.parallel=true，增量编译的缓存写入可能会发生并发问题。我曾在 CI 上遇到过一次「增量编译在并行构建中产生不一致的 outputs」的故障，最后把关键 Task 改成了 parallel = false 才解决。
总结几个要点
- 声明好 inputs/outputs 是增量编译的前提，别偷懒。
- 不要用动态值做 @Input，比如
System.currentTimeMillis()或UUID.randomUUID()——这会摧毁一切缓存。 - 善用构建扫描（Build Scan）分析 Task 为何不是 UP-TO-DATE。
- 对自定义 Task 做增量测试：先跑一次，改一个输入文件再跑一次，观察是否只执行了一次。
增量编译不是银弹，但用好了能省下大把的构建时间。在我现在的团队里，每次 Code Review 看到有人写自定义 Task 却不加 inputs 注解，我都会直接打回——嗯，职业病吧。