Gradle修改少量代码却触发大范围编译，大概率是增量构建失效而退化为全量执行；根源在于输入指纹追踪或class文件映射被破坏，如手动修改class、sourceSets未重载、不支持增量的注解处理器、隐式文件时间戳变更等。

Gradle 修改少量代码却触发大范围编译，大概率不是代码改得多，而是增量构建没生效——它退化成了全量执行。

为什么 compileJava 会扫完整个 src/main/java

Gradle 默认开启增量编译（options.incremental = true），但这个机制依赖两个前提：源文件的「输入指纹」可被准确追踪，且编译器输出的 class 文件能与源文件一一映射。一旦破坏任一条件，就会 fallback 到全量编译。

• 常见破坏点：手动修改了 build/classes/java/main 下的 class 文件（比如调试时热替换失败残留）
• 修改了 sourceSets 配置但没重载项目（如动态加了 src/gen/java，但 IDE 没刷新，Gradle Daemon 还按旧路径扫描）
• 用了不支持增量的注解处理器（例如老版本 lombok 或某些自定义 AnnotationProcessor），它会让整个 compileJava 任务标记为 @InputChanges 不安全
• 启用了 annotationProcessorPath 但没声明 classpath 的稳定性，Gradle 无法判断处理器是否变更

如何验证当前是不是真增量

运行 ./gradlew compileJava --info，重点看日志里有没有这行：

Skipping task ':compileJava' because it has no source files.

或者更关键的是：

Gradle 9.8.0

下载

Compiling with JDK Java compiler API.
Incremental compilation of 3 out of 12 classes completed.

• 如果看到 Skipping task，说明该任务被跳过，上游输入无变化
• 如果看到 Incremental compilation of X out of Y，说明增量生效
• 如果只看到 Compiling with JDK Java compiler API. 后直接进编译流程，没提“incremental”，基本就是退化了

gradle.properties 里这几个开关必须开

增量编译不是默认“全自动可靠”，它需要显式启用并规避已知干扰项：

• org.gradle.configuration-cache=true（配置缓存开启后，对构建逻辑的变更更敏感，反而有助于稳定输入边界）
• org.gradle.parallel=true（并行本身不直接影响增量，但避免模块间隐式依赖导致误判变更）
• org.gradle.caching=true（构建缓存开启后，即使某次触发全量，后续相同输入也能命中缓存，掩盖部分问题）
• 禁用 org.gradle.jvmargs=-XX:MaxMetaspaceSize=512m 这类过小元空间设置——Metaspace 不足会导致 javac 内部状态异常，间接让增量判定失效

最容易被忽略的「伪变更」来源

你以为只改了一个 .java，但 Gradle 看到的输入可能早已污染：

• resources 目录下有同名 .properties 或 .xml 被 IDE 自动保存（时间戳更新），而你的 processResources 任务又依赖于 compileJava 输出，形成隐式链式触发
• 使用了 @Generated 注解或 Lombok 的 @Builder，但生成的代码写入了 build/generated/sources，而该目录被错误加入 sourceSets.main.java.srcDirs，导致每次生成都当成新源码
• Git hooks 或 CI 脚本在 checkout 后执行了 chmod 或 touch，悄悄更新了文件 mtime，Gradle 按时间戳判断为变更（哪怕内容没变）

真正难排查的，往往不是 Gradle 做错了什么，而是它忠实地响应了你没意识到的输入变化。别急着调参数，先用 --info 看清它到底认为哪些文件变了。