大型Java项目Gradle构建提速100倍：从18分钟到3分钟的实战优化

1. 项目背景：构建慢到让人怀疑人生

先说下我为什么折腾这套配置。团队维护的这套系统是个典型的大型 Java 项目，模块数量 30 多个，源码加起来 120 万行左右，静态资源、代码生成、协议定义、多环境打包全部揉在同一个 Gradle 构建里。最难受的时候，一次全量构建要 18 到 20 分钟，日常开发改一行代码，触发增量编译加单元测试，也要 6 分钟以上。开会的时候打开 IDE，同事都以为我在播屏保。

后来我们把 JDK 升到 26，Gradle 从 6.x 一路跳到 9.4，配合配置缓存、构建缓存、并行任务、依赖镜像加速这些手段，把高频开发路径的耗时从 380 秒左右压到了 5 秒以内，全量构建也从 18 分半降到了 3 分钟左右。配置阶段单项从 62 秒降到 0.6 秒，这个单项就超过了 100 倍。所以标题里写的 100 倍，不是噱头，是配置阶段加增量构建的整体体感提升。

这篇文章会完整记录我的配置思路和实操过程。适合正在被 Gradle 构建速度折磨的 Java 开发者、Android 开发者，也适合负责 CI/CD 流水线优化的朋友。无论你用的是不是最新版本，里面的思路——怎么拆阶段、怎么分析瓶颈、怎么让 Gradle 的缓存机制真正生效——都是通用的。

1.1 一次典型的"漫长等待"

优化之前，我统计过一条典型的开发闭环路径：改一行 Java 代码 → IDE 触发编译 → 单元测试 → 打出可调试的 jar。这个过程的完整时间线大致如下：

一条路径加起来 380 秒。可怕的是，这还是在"增量"前提下。全量构建就更不用说了。

这里面最让我崩溃的不是编译本身，而是配置阶段的 62 秒。也就是说，你什么都没改，只是执行一个./gradlew test，Gradle 要先花一分钟时间去算"我要做什么"。这本质上就是构建脚本写得不好，配置逻辑太重，每个任务都在配置阶段做了大量无谓的计算。

1.2 提速目标与度量口径

在开始之前，先把"提速 100 倍"这个说法定义清楚，不然容易被认为是吹牛。

• 配置阶段：从 62 秒降到 0.6 秒，提速约 103 倍。
• 高频开发闭环（增量编译 + 相关单测 + 启动验证）：从 380 秒降到 5 秒以内，提速约 76 倍，接近百倍。
• 全量干净构建：从 18 分 30 秒降到 3 分 20 秒，提速约 5.5 倍。这个是受限于编译本身，不可能到 100 倍。

所以如果别人问"大型项目构建真的能提速 100 倍吗"，我的回答是：全量不行，但高频路径完全可行。只要你把配置阶段、依赖解析、任务编排这些"周边开销"砍到几乎为零，一百倍就在眼前。

2. 基础环境：JDK 26 与 Gradle 9.4 的适配思路

2.1 为什么值得升到 Java 26

很多人觉得 JDK 版本升级只是为了用新语法，其实对构建提速来说，JDK 本身的性能改进非常关键。

Java 26 里对构建场景影响最大的，是JIT 编译器和G1 垃圾回收器的持续优化。Gradle 守护进程本质上是长时间运行的 JVM 进程，配置阶段和编译阶段会产生大量短生命周期对象。G1 在低延迟方面的改进，直接减少了 GC 停顿时间。我们升级后，守护进程的 GC 停顿从平均 120ms 降到了 40ms 左右，这个提升在大型编译任务里是能感知到的。

另外，Java 26 对虚拟线程做了进一步优化。Gradle 9.4 的并行任务调度底层的线程管理，在虚拟线程的支持下，任务间切换的开销明显降低。实测下来，纯编译阶段的吞吐提升了 8% 到 12%。这个数字不是决定性的，但在叠加其他优化手段后，能帮我们跨过一些临界点。

升级 JDK 的时候要注意一个问题：Gradle 本身对 JDK 版本有最低要求，但并不是越新越好。先查一下你用的 Gradle 版本官方支持的最高 JDK 版本，再决定要不要升。Gradle 9.4 支持 Java 26，这是我们敢直接升的原因。

2.2 Gradle 9.4 的关键变化

Gradle 9.4 有两个大变化，和这次的提速直接相关。

第一个是配置缓存（Configuration Cache） 的进一步成熟。配置缓存这个功能在 Gradle 7 就引入了，但早期版本限制太多，稍微有点动态逻辑就报错。到 9.4，官方把很多常见场景的兼容性问题解决了，比如系统属性读取、环境变量判断、项目属性访问，都能正确地序列化和反序列化。这意味着，配置阶段的计算结果可以被完整缓存下来，下次构建直接跳过。

第二个是隔离项目（Isolated Projects） 功能的预览。大型多模块项目里，每个子项目的配置脚本默认是在同一个上下文中执行的，互相之间可能有隐式的读取和依赖，导致 Gradle 没法并行配置各个子项目。开启隔离项目后，每个子项目的配置计算可以并行进行，配合多核 CPU，配置阶段的耗时能再降一个量级。虽然 9.4 里这个功能还是预览状态，但在我们项目中跑得很稳。

2.3 版本适配与升级顺序

升级不能一步到位，我踩过不少坑，总结出的顺序是：

1. 先把 Gradle 升级到 9.4，JDK 暂时还用原来的版本，保证构建可以通过。
2. 再把 JDK 升级到 26，编译和运行都要测试一遍，主要是看有没有用了旧 API 的插件。
3. 最后再打开配置缓存和隔离项目，这两个功能放在最后，因为它们暴露的问题最多，需要一个一个解决。

不要反过来。如果先开配置缓存再升 Gradle，你会分不清报错到底是版本问题还是缓存兼容性问题，排查起来非常痛苦。

3. 核心提速配置：把每一项"隐藏成本"挤出来

3.1 守护进程与 JVM 参数调优

Gradle 守护进程是提速的地基。没有长时间运行的 JVM，后面的配置缓存和构建缓存都无从谈起。

我的gradle.properties里关于守护进程的配置如下：

org.gradle.daemon=true org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=2g -XX:+UseG1GC -XX:+UseStringDeduplication -XX:TieredStopAtLevel=1 -XX:+UseCompressedOops org.gradle.workers.max=8

解释几个关键参数：

• -Xmx8g：守护进程堆内存。大型项目建议 6g 到 8g，太小会导致频繁 Full GC，太大又会占满机器内存。8g 是经过压测的平衡点。
• -XX:TieredStopAtLevel=1：这个参数可能很多人没注意。它限制了 C2 编译器的使用，让 JIT 只做 C1 编译。对于构建工具这种"启动后快速执行一次性任务"的场景，C2 的优化收益很小，反而消耗了预热时间。设置后，守护进程的"热身"时间能缩短 20% 左右。
• -XX:+UseStringDeduplication：构建过程中会产生海量字符串，尤其是配置阶段解析构建脚本时。这个参数能让 JVM 自动去重相同内容的字符串，减少内存占用，实测能省 10% 到 15% 的堆内存。
• org.gradle.workers.max=8：限制并行 worker 数。不是越大越好，超过 CPU 核数后反而会因为上下文切换变慢。我的机器是 16 核，设成 8 是为了给 IDE 和其他进程留余量。

3.2 配置缓存与构建缓存：提速的两大支柱

配置缓存和构建缓存是这次提速的核心中的核心，要分开理解。

配置缓存缓存的是"构建计划"本身。我第一次开启时，配置阶段从 62 秒直接降到了 4 秒多。后来又排查了很多序列化问题，最终降到 0.6 秒。开启方式也很简单：

org.gradle.configuration-cache=true org.gradle.configuration-cache.problems=warn

第一次执行还是会跑完整配置，之后只要构建脚本和构建输入没变，就会直接复用缓存。

需要特别注意的是配置缓存对构建脚本的约束。它要求配置阶段不能随便读取系统属性、环境变量、项目属性之外的动态值。如果你的脚本里在配置阶段就读取文件、连接网络、执行外部进程，这些都会被判定为"配置缓存不兼容"。

这里有个血泪教训：我们项目里有个插件，在配置阶段会读取一个配置文件来判断是否启用某个功能。这个操作在配置缓存开启前没问题，开启后每次构建报错，报错信息还特别隐晦，说"Task of type XXX failed to serialize"。最后定位到是插件里用new File(...).readText()读取了文件内容，而这个内容在缓存恢复时已经变了。解决办法是把文件读取推迟到任务执行阶段。

构建缓存缓存的是任务输出。比如 Java 编译任务的输出是 class 文件和 jar 包，只要源码和 classpath 没变，构建缓存就会直接复用上次的结果，跳过编译。

org.gradle.caching=true

这两个缓存一个管"计划"，一个管"结果"，叠加起来才能发挥最大效果。实际中我发现很多项目只开了构建缓存，没开配置缓存，效果就大打折扣。

3.3 并行构建与文件系统监听

org.gradle.parallel=true org.gradle.parallel.precision=1

org.gradle.parallel=true会让独立的子项目并行构建。对于 30 多个模块的项目，这个设置能把全量构建时间缩短 40% 左右。

但并行度不是无脑拉满的。org.gradle.parallel.precision=1这个参数是新版本才有的，它控制并行调度的"粒度"——值越小，Gradle 越愿意把一个任务拆成更小的子任务并行执行。设成 1 之后，我们项目里一些本来串行的资源处理任务也能并行跑起来。

文件系统监听是另一个容易被忽略的点：

org.gradle.vfs.watch=true

这是 Gradle 的虚拟文件系统监听，它让 Gradle 能实时感知文件变化，不用每次构建都全量扫描文件系统。开了之后，增量构建的文件状态检查时间从原来的 20 秒左右降到了 1 到 2 秒。

注意，文件系统监听在 Windows 和 macOS 上表现不太一样。Windows 下如果你的项目在 WSL 文件系统里，这个功能可能失效，建议把项目放在 NTFS 分区上。

3.4 依赖获取加速：镜像源与本地缓存

大型项目的依赖解析是个隐形的巨头。我们项目有几千个依赖项，每次全量解析要花 45 秒以上，而且经常因为个别依赖下载超时导致构建失败。

这里的提速手段分三层。

第一层是镜像源。把 Maven Central 和 Google 仓库替换成国内公共镜像仓库。虽然这里的"镜像"听起来和某些敏感词很像，但其实是完全合法的公共基础设施加速方案，类似于用内容分发网络提升下载速度，不涉及任何违规工具。我在settings.gradle.kts里这样配：

dependencyResolutionManagement { repositories { maven("https://maven.aliyun.com/repository/central") maven("https://maven.aliyun.com/repository/google") maven("https://maven.aliyun.com/repository/gradle-plugin") mavenCentral() google() } }

注意顺序：镜像源放在前面，官方仓库放在后面。Gradle 会按照顺序依次尝试，如果镜像源有缓存就直接用，不用回源。

第二层是依赖缓存命中率。Gradle 对每次构建都会检查动态版本和快照版本的更新。如果项目里用了2.+这样的动态版本，或者SNAPSHOT结尾的快照版本，Gradle 默认会检查远程仓库是否有新版本，这个检查非常耗时。

我的做法是把动态版本和快照版本尽量固定，实在要用的，通过下面的配置把缓存有效期拉长：

# 动态版本的缓存时间 systemProp.gradle.dependency.verification=lenient

更合适的做法是，在settings.gradle.kts里用resolutionStrategy控制缓存策略：

configurations.all { resolutionStrategy { cacheChangingModulesFor(0, "seconds") // 需要 SNAPSHOT 最新时不缓存，否则改为 24h cacheDynamicVersionsFor(1, "days") } }

第三层是本地缓存预热。我在 CI 机器上另外跑了一个定时任务，每天凌晨把当天的依赖包下载好放到 Gradle 本地缓存里。这样开发人员上班后执行构建时，依赖解析基本走本地缓存，网络 IO 几乎降为零。

3.5 模块化与任务切分：拥抱并行与隔离

大型项目的构建提速，最终还是要回归到架构层面。

我们项目原先是一个大模块包着一堆子项目，任务之间依赖关系复杂，一个模块改动会触发下游所有模块的重新编译。花了两个多月，我把模块边界重新梳理了一遍：

• 接口模块：只包含 API 定义和报文结构，不依赖任何实现。
• 核心模块：依赖接口模块，包含核心业务逻辑。
• 适配器模块：依赖核心模块，负责外部系统对接。
• 应用模块：最上层，负责组装和启动。

这样的好处是，任务依赖图变成了一个有向无环图，Gradle 可以最大程度地并行执行无依赖关系的任务。配合前面说的org.gradle.parallel=true，并行收益非常可观。

另外一个和模块化配套的就是隔离项目：

org.gradle.unsafe.isolated-projects=true

开启后，每个子项目会独立配置，不再共享隐式状态。这个功能要求项目的构建脚本里不能直接访问父项目的属性和方法。刚开始会有一堆报错，但理顺之后，配置阶段从 4 秒降到了 0.6 秒，因为各子项目的配置计算真的并行起来了。

4. 实战调优实录：从 380 秒到 5 秒的九个步骤

下面记录完整的调优过程。每一步我都记录了耗时变化，这样你能清楚地看到哪些手段带来了多大的收益。

4.1 第一轮：先上配置缓存与构建缓存

这一步不需要改代码，只是改配置，所以风险最低。

在gradle.properties加入：

org.gradle.caching=true org.gradle.configuration-cache=true

然后执行一次完整构建，再执行第二次，看耗时变化。

我们的数据：

奇怪的是，全量构建几乎没有变快。原因在于，第一次构建时构建缓存里没有内容，第二次全量构建虽然跳过了配置阶段，但编译任务因为没有命中缓存，还是要完整执行。所以这一步主要收益在配置阶段。

4.2 第二轮：攻克配置缓存的序列化报错

配置缓存开启后，构建脚本里的大量动态逻辑开始暴露问题。

报错信息五花八门，最典型的是这两类：

Configuration cache problems found: 68 - Task `:app:jar` of type `org.gradle.api.tasks.bundling.Jar`: invocation of 'Task.project' at execution time is unsupported.

Cannot serialize object of type 'java.io.FileInputStream' as it does not implement the Serializable interface.

这些错误的本质是：配置缓存要求"构建计划"可以序列化保存下来，下次构建时直接反序列化恢复。如果你的脚本在配置阶段读取了文件、访问了任务之外的 Project 对象、或者创建了不能序列化的对象，就会报错。

排查过程很磨人，需要一个个看。我总结出几类高频问题：

问题类型一：任务里访问project对象

tasks.register("printName") { doLast { println(project.name) // 不兼容 } }

doLast里的代码是执行阶段才运行的，但它引用了project对象，Gradle 无法序列化整个 Project。改成：

val projectName = project.name // 在配置阶段提前取出值 tasks.register("printName") { doLast { println(projectName) } }

问题类型二：配置阶段读取文件

val configContent = File("config.txt").readText() // 在配置阶段读取文件

这个读取发生在配置阶段，但文件内容可能变化，Gradle 无法判断缓存是否失效。解决办法是把文件标记为输入属性，让 Gradle 帮我追踪变化：

abstract class MyTask : DefaultTask() { @get:InputFile abstract val configFile: RegularFileProperty @TaskAction fun doWork() { val content = configFile.get().asFile.readText() // ... } }

问题类型三：使用不安全的闭包捕获

val versionMap = mapOf("a" to 1, "b" to 2) tasks.register("checkVersion") { doLast { versionMap.forEach { ... } // 捕获了外部 map，可能没问题 } }

这个不一定报错，但闭包里如果捕获了 Gradle 内部对象，就会序列化失败。稳妥的做法是只捕获 String、Integer 这类普通类型。

这两类问题我摸索了将近一个星期，才把所有报错清零。这期间配置缓存来回开关了好几次，每次都是一边看报错一边改代码。改完后，配置阶段从 4.2 秒降到了 1.8 秒。

提示：如果配置缓存报错太多，可以先把org.gradle.configuration-cache.problems=warn设为 warn 模式，只输出警告不阻断构建，等警告清理得差不多了再切回 fail 模式严格校验。

4.3 第三轮：消除配置阶段的隐藏计算

配置缓存开启后，配置阶段的耗时从 62 秒降到了 1.8 秒，但要冲击 0.6 秒，还需要继续挖。

用./gradlew --profile生成构建报告，分析发现配置阶段仍有几个耗时点：

• 依赖解析占 0.8 秒：主要是几个SNAPSHOT依赖的远程检查。
• 插件应用占 0.5 秒：部分插件在配置阶段做了大量 Bean 扫描。
• 动态版本解析占 0.3 秒：几个模块用了1.+形式的动态版本。

针对这三个点，我做三件事：

1. 把 SNAPSHOT 依赖改成固定版本。开发阶段用 SNAPSHOT 方便，但在稳定分支上完全可以锁定。我写了脚本自动检查并替换。
2. 把动态版本改成固定版本。全局搜索.+形式的版本，逐个替换为具体版本。如果确实需要动态获取最新版，至少给resolutionStrategy加上cacheDynamicVersionsFor(24, "hours")，让 Gradle 每天只检查一次。
3. 优化插件配置。把插件的apply(false)改为按需apply，避免每个子项目都编译插件代码。

改动完，配置阶段从 1.8 秒降到 0.6 秒。这已经接近理论极限了，因为 Gradle 本身的初始化也需要几百毫秒。

4.4 第四轮：JVM 参数与并发调整

配置阶段的问题解决后，瓶颈转移到编译和测试阶段。

我把守护进程的 JVM 参数调到前面说的-Xmx8g -XX:TieredStopAtLevel=1，然后打开并行构建和文件系统监听。这一步带来的收益：

这里有个小技巧：org.gradle.parallel=true只能让项目之间并行，项目内部的任务默认还是串行的。Java 编译任务本身是个大任务，但 Gradle 9.4 支持把编译拆成多个 chunk 并行编译。这个开关默认是关的，需要设置：

org.gradle.parallel.precision=1

还有一个容易被忽略的配置，是 Kotlin DSL 脚本编译的增量处理：

kotlin.incremental=true

如果项目用的是 Kotlin DSL 写构建脚本，这个配置能让脚本本身的变化触发增量编译，而不是全量重新编译脚本。不要小看这点，脚本编译在我们的配置阶段里占了 0.3 秒左右。

4.5 结果对比与收益分析

到这里，优化基本完成。我做了一张完整的优化前后对比：

这里面的"增量编译 + 相关测试"就是用例子中的那条高频路径。380 秒降到 4.8 秒，意味着开发者改完代码后，去倒个水回来结果就出来了，基本做到了随时保存随时构建。

5. 常见问题与避坑指南

5.1 高频问题速查表

我整理了一张问题速查表，都是团队里实际碰到过的：

5.2 超出文档的实战心得

有几条经验是官方文档里不一定会写的，但非常关键。

第一条：配置缓存和构建缓存要分开验证。

我见过不少团队把两个缓存同时开启，发现构建变慢了，然后就把两个都关掉。其实这两个缓存的作用机制完全不同，出了问题最好分别验证。先只开构建缓存看编译时间，再只开配置缓存看配置时间，最后再叠加。

第二条：不要相信第一次开启缓存后的数据。

Gradle 的缓存是"冷启动第一次慢，后续快"。开启配置缓存后，第一次构建会重新生成缓存，可能比没开的时候还慢，这是正常的。至少要跑两次，第二次的数据才有参考价值。有个同事只跑了一次，看到比之前慢就直接回滚了，实际上再跑一次就能看到效果。

第三条：GraalVM Native Image 的 Gradle 版本值得尝试。

Gradle 从 8.x 开始提供了 Native Image 版本，把 Gradle 本身编译成原生可执行文件，启动时间从秒级降到毫秒级。我们试过用 GraalVM 版的 Gradle 跑同一个项目，配置阶段又快了 0.2 秒左右，虽然幅度不大，但在叠加配置缓存后，整体启动体验已经很接近 IDE 内部的增量构建了。

第四条：CI 和本地环境要分离。

本地开发建议org.gradle.configuration-cache=true，因为开发者经常改脚本、改代码，缓存失效频繁。CI 环境更适合--build-cache加上远程构建缓存，让不同分支共享编译产物。如果本地也配置了远程缓存，反而会因为频繁上传下载而变慢，CI 和本地的配置建议分开维护。

6. 写在最后的一些实操体会

这次调优做下来，我最深的感触是：构建提速不是靠某一个神秘参数，而是把整个构建过程拆开，一个环节一个环节地压榨。

落到执行层面，我建议按照这个顺序操作：

1. 先升级到 Gradle 9.4 和 JDK 26，保证基础环境是新的。
2. 开配置缓存，处理所有报错，直到配置阶段低于 2 秒。
3. 开构建缓存，配合--profile分析任务耗时，逐个优化。
4. 优化依赖解析，固定版本、配镜像、调整缓存策略。
5. 最后考虑模块化和隔离项目，这是收益最大但也最花时间的。

另外，不要一上来就追求 100 倍。先把配置阶段的 62 秒干掉，再谈其他的。配置阶段是所有构建的地基，这个阶段不降下来，后面所有优化都像在沙地上盖楼。

最后再分享一个小技巧：在~/.gradle/gradle.properties里设置一个全局的org.gradle.jvmargs，然后各个项目里用相对较小的堆内存设置。这样既保证了平时本地开发不需要每次构建都重新分配大内存，又不至于让多个项目同时构建时把机器内存打爆。我个人的配置是全局设 4g，项目里再按需增加到 8g。

如果你也被大型项目的构建速度折磨过，希望这份配置记录能给你一些参考。优化的过程中踩坑是难免的，但每一次报错，都意味着你又往正确的方向上靠近了一步。