Gradle增量构建从原理到实战：告别全量构建，提升多模块编译效率

先问一句：你所在的项目是不是也这样——改了一行日志代码，等整个项目编译、打包跑完，水都接回来喝完了，结果还没跑完。如果你在一个多模块的 Gradle 项目里待过，这种场景应该不陌生。Gradle 的增量构建，就是专门来治这个心病的。它的核心目标很朴素：只构建修改过的模块与代码，其余没动过的地方全部跳过。这篇文章我打算从机制讲到实操，再把我这些年踩过的增量构建相关的坑和排查思路都整理出来，适合刚接触 Gradle、被“全量构建”折磨的开发者，也适合已经用 Gradle 但发现“明明配了增量，却还是每次都全量”的团队参考。

1. 增量构建到底在解决什么问题——先把思路理清

1.1 构建变慢，慢在哪

很多团队一开始没意识到，构建慢的根本原因不是“代码太多”，而是“重复做了太多没用的事”。一个典型的多模块项目，可能有 app、core、feature-login、feature-order 等十几个甚至几十个模块。你只改了 feature-login 里的一个常量，理论上只有这一个模块的编译和它下游的打包受影响，但如果没有增量构建，Gradle 会老老实实地把整个依赖链上的任务全部重跑一遍。为什么？因为它不知道哪些输入没变，或者你的任务压根没有声明输入输出，它只能默认“每次都重跑最安全”。

从构建耗时分布上看，这种浪费非常明显。配置阶段要执行所有项目的 build.gradle，依赖解析要检查仓库里的快照，编译阶段要把大量没变的 .java、.kt 再翻译一遍 class，打包和测试更是直接把时间拉满。增量构建要做的，就是逐个环节减少这种“确定性重复劳动”。

1.2 Gradle 能做的四个层面的“增量”

很多人把“增量构建”理解成“只编译改过的文件”，这其实只是其中一层。Gradle 的增量体系是分层的，我习惯把它拆成下面四个层面：

这五个层面不是互斥的，而是叠加生效。配置缓存解决“配置慢”，任务级增量解决“重复任务执行”，编译级增量和编译避免解决“重复编译”，构建缓存则把“之前在任何地方跑过的结果”直接拿过来用。现在的 Gradle 构建速度能优化到“秒级”，靠的就是这几层同时工作。

1.3 增量构建和构建缓存的关系

有不少人分不清“增量构建”和“构建缓存”，这里说下我的理解。任务级增量的本质是“本地历史对比”：这次跑了任务之后，Gradle 记下输入输出的快照，下次构建时对比发现都没变，就标记 UP-TO-DATE 跳过。这种机制有个局限——换一台机器或者清理本地缓存后，历史对比就没了，一切又得从头跑。

构建缓存则是把任务的输出结果按输入哈希值存储起来。只要任务的输入哈希相同，不管是在本地、CI 还是同事的电脑上，Gradle 都可以直接拉取缓存里的结果，标记为 FROM-CACHE。所以构建缓存更像是增量的“远程增强版”，它不取代增量，但把增量的覆盖范围从“单机单次”扩大到了“任何地方”。实际项目中，这两者往往是同时开启的。

2. 核心机制拆解：Gradle 怎么判断“要不要重新构建”

2.1 任务的输入输出声明与 UP-TO-DATE 检查

要理解增量构建，先要理解 Gradle 里一个 Task 的基础结构：输入（inputs）、输出（outputs）、动作（action）。Gradle 在第一次执行任务时，会对输入和输出做快照记录，然后保存执行历史。第二次构建时，它先重新计算输入和输出的状态，再和历史快照对比：如果完全一致，任务直接跳过，在日志里标记为 UP-TO-DATE；只要有一个文件不同、一个属性值变了，这个任务就会重新执行。

这里最关键的一点是：Gradle 不会自动知道你的任务“吃了什么、吐了什么”。内置任务比如 JavaCompile、Copy 都已经声明好了，但你自己写的自定义任务如果没有声明输入输出，那 Gradle 每！次！都！会！执！行！。这也是很多项目“明明配了增量却不生效”的最常见原因。我在改造老项目时，每次看到自定义任务没有 inputs/outputs 声明，基本就明白为什么构建一直快不起来了。

2.2 常用输入输出注解清单与避坑

Gradle 提供了几种注解来标记任务属性，核心是这几个：

声明这些注解时我踩过几个坑。首先是输出目录和输入目录不能重叠，有些偷懒的写法会把 build 目录既当输入又当输出，结果就是快照永远对不上，任务永远重跑。其次是不要用当前时间、随机数作为@Input属性，这等于主动告诉 Gradle“我的输入每次都变”，缓存直接失效。最后是@Optional要谨慎用，它只用于“可能不存在”的合法输入，不是让你省事不传参的。

2.3 编译增量与注解处理：最容易踩的坑

JavaCompile 任务本身支持增量编译，但一旦引入了注解处理器，情况就复杂了。Gradle 对注解处理器采取偏保守的策略：如果处理器不支持增量模式，Gradle 就无法准确判断“哪些类会受影响”，于是只能扩大重编译范围，甚至退化成全量重编译。这也就引出了很多人见过的那条 IDEA 提示：“java: jps 增量注解进程已禁用。部分重新编译的编译结果可能不准确。使用构建进程”。

这条提示出现的原因，是 IntelliJ IDEA 默认用自己的 JPS 构建系统来编译，而 JPS 检测到某些注解处理器与它的增量编译机制不兼容，为了不产错误结果，主动禁用了增量注解进程。注意，这里说的“构建进程”指的是构建工具进程，也就是当你把 IDEA 的“Build and run using”设置为 Gradle 之后，由 Gradle 来统一负责编译，这个提示就不会成为限制。我的建议是：项目里有 Lombok、MapStruct 这类注解处理器的时候，尽量让 Gradle 统一接管编译，而不是混用 IDEA 的 JPS 和 Gradle 两套机制。

如果需要保留注解处理器，又想尽量增量，可以检查 Gradle 日志里是否有关键字眼：如果某个任务因为注解处理器不兼容而无法增量，Gradle 会降级并提示使用 non-incremental mode。这时候只能升级注解处理器、换兼容版本，或者接受对该模块的全量重编译。

2.4 编译避免（Compile Avoidance）与 ABI 快照

编译避免是我觉得 Gradle 最被低估的一个功能。它的核心思想是：如果模块 A 依赖模块 B，B 的实现变了但公开 API（方法签名、注解等）没变，那么 A 就不需要重新编译。因为 Java 编译只关心 class 文件对外暴露的接口，不关心方法体内部怎么实现的。

Gradle 在 Java 9 之后对 ABI 快照的支持更完善，它会为每个 classpath 上的文件生成 ABI 快照。现在 Java/Kotlin 项目的多模块增量构建，很大程度上依赖这一机制。实测下来，在核心模块里修改一个私有方法的实现，下游所有依赖模块的 compile 任务大部分都会显示 UP-TO-DATE，这比“看到模块 M 变了就全量重编下游”高效得多。但如果你的项目用了 Kapt、某些会修改 class 字节码的插件，编译避免可能被破坏，因为 Gradle 无法确定字节码变换是否会影响 ABI。

3. 实操：从配置到验证，让项目真正跑起增量构建

3.1 环境与全局配置：别让版本和参数拖后腿

在看具体任务配置前，先检查 gradle.properties。我建议至少保证下面这些参数存在：

org.gradle.daemon=true org.gradle.parallel=true org.gradle.caching=true org.gradle.configuration-cache=true org.gradle.configuration-cache.problems=warn org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g

• org.gradle.daemon=true：复用 Gradle 守护进程，避免每次构建都启动 JVM。
• org.gradle.parallel=true：模块间无依赖关系的任务并行执行，多模块项目收益很直接。
• org.gradle.caching=true：开启构建缓存，配合增量构建效果翻倍。
• org.gradle.configuration-cache=true：缓存配置阶段结果，避免每次构建都重新执行所有 build.gradle。新版本 Gradle 对它的支持已经很成熟，但如果项目里有很多老插件，可以先开警告模式，也就是同时配置problems=warn，观察一段时间再彻底开启。

这里要提醒一点：热词里很多人搜“gradle 安装配置”“IDEA 配置 gradle”，其实配置的关键不是“把 Gradle 装上”，而是“让构建参数处于正确状态”。如果你用的是 wrapper，尽量保持一个较新的 Gradle 版本；老项目盲目升到 9.x 可能遇到插件兼容问题，但长期停在 6.x 也享受不到配置缓存和编译避免的改进。

3.2 多模块项目改造：哪些配置直接影响增量效果

多模块项目最影响增量的，是模块依赖声明方式。我见过很多项目大量使用api而不是implementation，这等于让依赖传递范围扩大，下游模块的 classpath 里塞进了本来不需要的依赖，任何一点变化都可能触发下游重编译。如果不是需要暴露给下游的 API，一律用implementation。

其次是自定义任务的写法。假设你有一个生成版本文件的任务：

abstract class GenerateVersionFileTask extends DefaultTask { @Input abstract Property<String> getVersion() @OutputFile abstract RegularFileProperty getOutputFile() @TaskAction void generate() { outputFile.get().asFile.text = """version=${version.get()}""" } } tasks.register('generateVersionFile', GenerateVersionFileTask) { version = project.version.toString() outputFile = layout.buildDirectory.file('generated/version.properties') }

注意这里用了tasks.register，而不是task。后者是立即创建任务，前者是延迟创建，不会在配置阶段就触发任务对象的完整初始化，对配置缓存和配置速度都有好处。abstract class+Property的写法，让 Gradle 能自动感知输入输出，避免了手写 getter/setter 时的遗漏。

还有一个实操技巧：不要在配置阶段直接执行耗时操作。比如在 build.gradle 顶层写def files = fileTree('src').collect { ... }，这种代码在每次配置阶段都会跑，而且可能被配置缓存标记为不可缓存任务。正确的做法是把这类操作放进doFirst或doLast，也就是任务真正执行时才做。

3.3 验证增量是否生效的三种方法

配置完之后，怎么确认增量真的生效了？我常用三种方式。

第一种是连续跑两次同样的任务，观察第二次日志里的状态标记。比如：

./gradlew :app:compileDebugJavaWithJavac --info ./gradlew :app:compileDebugJavaWithJavac --info

第二次如果出现UP-TO-DATE，说明任务级增量生效；如果出现FROM-CACHE，说明命中了构建缓存。

第二种是改一个模块的源码后再构建，看哪些任务重新执行。正常情况下，只有被改模块及其直接下游的 compile、package、transform 等任务会执行，其它模块应该保持 UP-TO-DATE。

第三种是用构建扫描：

./gradlew build --scan

构建扫描会生成一份网页报告，能直接在报告里看到每个任务的耗时、缓存命中情况、是否 UP-TO-DATE、为什么缓存 miss。排查“我明明配了增量但它每次都全量跑”这类问题时，构建扫描是效率最高的工具。我一般先看“Task execution”列表，按耗时排序，优先处理那些每次都在跑、耗时长、且没有命中缓存的任务。

3.4 进阶：本地构建缓存与远程构建缓存

本地构建缓存开启后，Gradle 会在用户目录下维护一个构建缓存目录，通常位于~/.gradle/caches/build-cache-1。它的作用是把任务输出按输入哈希存储起来，即使任务历史被清理了，只要输入哈希一致，仍然能命中缓存。

远程构建缓存更适合团队和 CI 场景。配置方式是在 settings.gradle 里加上：

buildCache { local { enabled = true } remote(HttpBuildCache) { url = 'https://build-cache.example.com/cache/' push = true } }

CI 上跑过一遍后，开发者在本地拉代码再构建时，大部分重活都能直接从远程缓存拉取，不需要本地再编译一遍。不过要提醒一句：远程缓存不要裸奔在公网，至少加上身份认证，输出的构建产物可能包含内部信息，这点一定要有安全意识。

4. 常见问题与排查技巧实录

4.1 配置缓存不生效，配置阶段依然慢

表现：gradle build每次都在 Configuration 阶段停留很久，日志里出现类似于“Configuration cache entry could not be reused”或者一大堆 problem 提示。

原因通常是构建脚本里使用了不兼容配置缓存的 API。最常见的有：在配置阶段执行外部命令、直接读取系统属性来修改任务行为、使用project.afterEvaluate做太多事情、动态创建任务且无法序列化。排查方法是在 gradle.properties 里开启org.gradle.configuration-cache.problems=warn，然后跑一次构建，Gradle 会把所有不兼容点列出来，逐个修就行。

我处理过的项目里，很大一部分“慢”并不是编译慢，而是配置阶段每天都要花好几秒。把配置阶段时间压到 1 秒以内后，整个构建体验会明显不同。

4.2 注解处理器让“部分重新编译”变成全量

表现：模块里只改了一个类，但整个模块的 .class 全部重新生成，甚至下游模块也重新编译。同时 IDEA 里可能看到“java: jps 增量注解进程已禁用。部分重新编译的编译结果可能不准确。使用构建进程”提示。

这条 IDEA 提示的本意不是说代码错了，而是 JPS 发现注解处理器不支持增量，为了安全不生成不可靠的编译结果，只能禁用增量。如果你不想看到这种提示，或者想得到更稳定的增量效果，建议在 IDEA 的 Build Tools 里把 Gradle 的“Build and run using”从默认的 Gradle 设置确认打开，让所有编译统一由 Gradle 负责。

如果你用 Kotlin，还应该确认kotlin.incremental=true以及 kapt 的增量模式是否开启。注意，有些注解处理器本身就不支持增量，这类问题只能通过升级处理器版本来解决，如果实在不行，接受单模块全量编译也比整个项目全量好。

4.3 依赖缓存损坏、下载超时怎么处理

表现：构建报Gradle's dependency cache may be corrupt，或者下载依赖时出现java.net.SocketTimeoutException。

依赖缓存损坏的常见原因，是网络中断导致下载了一半的 jar 被当成完整依赖缓存下来。处理方法很简单：定位到报错的依赖，删除~/.gradle/caches/modules-2/files-2.1下对应的 group/artifact 目录，然后重新同步。如果损坏范围很大，直接删掉整个 modules-2 目录重新下载也行，代价只是多花点下载时间。

下载慢和超时是另一个痛点。Gradle wrapper 的 distributionUrl、依赖下载都可能因为网络原因非常慢。我通常会在两个层面处理：一是把 maven 仓库换成镜像源，在 settings.gradle 里配置阿里云或其他国内镜像；二是如果 wrapper 的 distribution 下载太慢，手动下载对应 zip 放到~/.gradle/wrapper/dists对应的临时目录里。这里特别提醒：不要为了“快点拿到最新依赖”就随手加--refresh-dependencies，这个参数会强制刷新所有动态版本，把构建拖慢一大截，而且和增量缓存完全是两回事。

4.4 任务永远不缓存：时间戳与输出污染

表现：任务输入输出都没变化，但每次构建还是执行，日志里始终没有 UP-TO-DATE。

原因通常出在“输入”上。我排查过几种典型情况：任务输入里包含当前时间戳或随机字符串；某个@InputFiles指向的目录包含另一任务的输出文件，导致每次构建这个目录内容都在变；文件权限变化也会触发快照不一致，但这类相对少见；还有就是把临时文件放在了源目录下，被输入收集时误判。

遇到这种问题，先用构建扫描或--info日志找到具体是哪个任务，再看它的输入声明。如果是时间戳，就把时间戳移到任务动作里，而不是当输入；如果输入目录总是变化，考虑收缩输入范围，只声明真正参与计算的源文件。

4.5 Gradle 版本与 JVM 版本不匹配的排查

表现：构建直接报The project's Gradle version 6.7.1 is incompatible with the Gradle JVM version，或者Could not install Gradle distribution from '...'。

这些问题虽然不直接属于“增量构建”，但会挡住你体验增量构建的路。Gradle 版本和 JDK 版本有对应关系，JDK 太新、Gradle 太旧时，Gradle 直接拒绝启动。处理方式有三种：升级 wrapper 到与新 JDK 兼容的 Gradle 版本；或者给项目配置一个合适版本的 JDK；又或者用 Gradle Toolchains 指定编译用的 JDK 版本。

Could not install Gradle distribution大多是网络问题导致 distribution 下载失败。解决办法和依赖下载类似：换 distributionUrl 镜像，或者手动下载 zip 后放到 wrapper 的 dists 目录下。当前各种热词里频繁出现的 Gradle 9.x 版本，对新项目来说功能更全、配置更快，但老插件项目升级前最好还是先在分支上试跑一遍构建扫描。

最后分享一点个人体会。我接手过的几个老项目，一开始都抱怨“Gradle 就是慢”，但真正用构建扫描把任务一个个扒开看之后，发现慢的原因大多是自定义任务没声明输入输出、模块依赖用了过宽的 api、配置阶段执行了不该执行的代码。这些东西不是 Gradle 的问题，是使用姿势的问题。给新项目从第一天就把任务输入输出写清楚，比等项目大了再回头改造省太多力气。如果你现在正被“全量构建”折磨，不如先从./gradlew build --scan开始，看看你那台机器上到底哪些任务在重复劳动。