干这行年头多了，你会发现一个特别扎心的规律：项目越大，构建越慢，慢到你把泡面煮好回来它还没跑完。我们之前那个单体老项目，几十个模块、几百个依赖，Gradle 6.9 + JDK 11 的时代，增量构建平均两分钟起步，全量构建随随便便九分多钟。后来新项目我们用上 Gradle 9.4 + Java 26，把构建配置彻底打磨了一遍，增量构建压到 2 秒上下，首次冷构建之后触发缓存全命中，体感就是秒过。按最坏情况对比，构建提速确实能到 100 倍这个量级。这篇文章就围绕这套组合，把大型项目构建提速的完整配置思路、关键参数、踩坑记录全部摊开讲，给你一条可以直接照抄的路。
先说明一点：100 倍不是玄学，也不是每个项目都能复现，它取决于你是否把 Gradle 的缓存机制、配置缓存、并行执行、依赖解析这几块全部吃到位。单独调一个参数肯定到不了这个效果，但整套配置落下去，像我们这种规模的 Java 项目，构建时间从八分半降到五秒以内是实打实的效果。下面的内容会先讲清楚构建慢的根源在哪里，再给出版本选型依据、完整配置文件和实操细节，最后是一份常见问题排查表，都是我们在实施过程中真正遇到过的。
1. 提速前先看懂瓶颈：构建慢的根源到底在哪
很多人一上来就抄配置，抄完发现没效果，然后骂教程是假的。其实不是配置没用，而是你根本没搞清楚自己的构建时间花在哪个阶段。Gradle 构建过程可以拆成三个阶段：初始化、配置、执行。不同阶段的耗时占比，决定了你该用哪一套优化策略。
1.1 Gradle 构建的三个阶段分别是做什么的
初始化阶段负责解析 settings 文件、确定项目结构、创建项目实例。对于单模块项目，这个过程能快到几十毫秒，但对于大型多模块项目，settings 里如果写了复杂的 include 逻辑、动态加载脚本，这一步也会产生可感知的开销。
配置阶段是重灾区。Gradle 会执行每个模块的 build.gradle 或 build.gradle.kts 脚本，解析依赖、创建 Task 对象、构建整个任务图。注意，这个阶段其实还什么都没干，它只是把“该做什么”这件事规划出来。如果脚本里写了大量 println、文件扫描、网络请求、动态版本解析，配置时间会指数级上升。传统的 Gradle 构建最大的痛点就在这里——每次构建都必须重新跑一遍配置阶段，哪怕你只改动了一个 Java 文件。
执行阶段才是真正干活的阶段，包括编译、处理资源、打包、测试等。这个阶段的优化空间在增量编译和任务输出的缓存上。如果配置阶段耗时 50 秒，执行阶段才 20 秒，你把 CPU 从 4 核加到 16 核，收益依然有限，因为大头在配置阶段卡死了。
1.2 大型项目里三个最隐蔽的拖累点
结合我们的项目实际，我总结出三个最隐蔽的拖累点。
第一个是动态版本依赖。比如你写了一个implementation "org.foo:bar:1.+"，Gradle 每次构建都必须联网请求仓库去查询这个范围内最新的版本号，还要按最短路径原则去解析冲突。这个查询过程单次可能只要几百毫秒，但项目里如果有几十个这种动态版本，叠加起来就是十几秒。更坑的是，远程仓库响应慢的时候，这个时间会指数级膨胀。
第二个是守护进程配置不合理。Gradle 守护进程是常驻后台的 JVM，如果没有给它足够的堆内存，或者 GC 和类加载配置不合适，频繁触发 Full GC，构建时间会在不知不觉中被吃掉几十秒。我们排查的时候发现，守护进程默认堆只有 1GB，连一个中型项目的依赖元数据都快装不下了。
第三个是任务没有声明输入输出。Gradle 的增量构建机制依赖 Task 的输入输出快照。如果你的自定义任务只是执行一个动作，却没有显式声明@Input、@OutputFile或@TaskAction相关注解，Gradle 无法判断这个任务是否需要重新执行。结果是每次构建，这个任务都会被当作“有变更”处理，所有下游任务被迫全部重跑。大型项目里这种隐性失效一旦扩散到几十个任务，增量构建就彻底成了全量构建。
我把这三个点放在前面说，是因为后面所有配置的最终目的，都是从这三个根源上动手。你如果理解了这三块，再看后面的配置就不会觉得是在堆参数了。
2. 版本选型与环境准备：为什么是 Gradle 9.4 + Java 26
先说版本选型。Gradle 9.x 系列对构建缓存和配置缓存做了大量底层优化，特别是配置缓存，从 7.4 引入的 experimental 状态到 8.x 的稳定，再到 9.x 的大规模性能提升，这个功能才真正适合大型项目使用。而 Java 26 作为长期演进中的一个版本，在编译器和 JIT 编译上又有明显改进，加上对虚拟线程等特性的进一步成熟，对 Gradle 这种重度并行场景非常友好。
2.1 Gradle 9.4 在大型项目上的几个关键改进
Gradle 9.4 我实测下来，最感觉到变化的是三个地方。
第一是配置缓存的稳定性。在 8.x 时代，配置缓存虽然很强大，但不少插件不兼容，开启之后要么报错要么悄悄禁用。9.4 这一代，主流的 Java、Spring Boot、Dependency Management 插件基本都兼容了，配置缓存可以放心打开。配置缓存的核心作用是把配置阶段的结果序列化下来，下次构建直接复用，也就是说那 50 秒的配置阶段可以被压缩到几百毫秒甚至零。
第二是构建缓存粒度的优化。9.x 的本地构建缓存改进了对输出文件的索引方式，缓存命中率比 8.x 有明显提升，尤其是在二进制依赖比较多、任务输出文件比较大的场景里，旧版本缓存写入和读取都比较慢，9.4 做了进一步的优化，命中速度更快。
第三是对工具链的自动检测。Gradle 9.4 配合 Java 26，可以通过java toolchain机制自动发现系统里安装的 JDK，按项目要求选择正确的版本编译。这个对于团队协作来说特别有用，再也不用每个人手动改 IDE 的 JDK 路径了。
2.2 安装配置与国内镜像源的正确打开方式
安装这块就直接说结论。不建议手动下载 zip 包然后解压配环境变量，虽然那样也能用，但版本切换很麻烦。个人开发者可以用 SDKMAN 来管理：
# 安装 SDKMAN curl -s "https://get.sdkman.io" | bash # 安装 Gradle 9.4 sdk install gradle 9.4 # 切换默认版本 sdk default gradle 9.4公司团队维护的构建环境建议直接用 wrapper，把 Gradle 版本固化在项目里，避免“我这能编译你那不行”的经典扯皮。wrapper 配置在gradle/wrapper/gradle-wrapper.properties：
distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-9.4-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists这里有一个很关键的点：默认的distributionUrl指向services.gradle.org，国内网络访问经常超时。解决方案是换成国内镜像地址。阿里云和腾讯云都提供 Gradle 发行包镜像，实测下来速度非常稳。改成这样：
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.4-bin.zip另外在~/.gradle/init.gradle.kts（或者init.gradle）里配置仓库镜像，让项目所有依赖解析都走国内 Maven 镜像。这里用 init script 的好处是全局生效，不需要改每个项目的repositories配置：
allprojects { repositories { maven("https://maven.aliyun.com/repository/public") maven("https://maven.aliyun.com/repository/gradle-plugin") maven("https://maven.aliyun.com/repository/spring") mavenLocal() mavenCentral() } }注意，mavenLocal()是有争议的。本地仓库里如果有旧版本的损坏包，反而会干扰构建。我的建议是只在明确知道自己要复用本地缓存的场景才打开mavenLocal()，否则宁可把它注释掉，让构建从远程镜像拉取，保证一致性。
提示：
GRADLE_USER_HOME默认是~/.gradle。构建缓存、守护进程日志、wrapper 下载的发行包都存在这个目录。建议把它放到一个空间大、读写快的磁盘上，有条件的话可以放到 NVMe 固态硬盘，效果立竿见影。
镜像配置这块还有个小技巧：如果项目里同时用到了多个插件仓库，建议把 Google 仓库也做镜像或者干脆去掉，只保留必用的仓库，能减少依赖解析时的仓库探测时间。Gradle 每解析一个依赖都会按仓库顺序逐一查询，仓库越多解析越慢。
3. 核心提速三板斧：缓存、并行、守护进程
环境就绪后，真正的提速配置集中在两处：一个是gradle.properties里的全局参数，一个是对项目结构的清洗。这一节先讲全局参数，也就是很多人说的“三板斧”。
3.1 构建缓存：让重复劳动真正消失
构建缓存和增量构建是两个不同层面的机制，但很多人混为一谈。增量构建是同一台机器上，判断任务输入是否变化，没变化就不执行；构建缓存则是把任务输出保存下来，任何机器、任何时间，只要输入哈希一致，就可以直接复用输出，连编译都不用跑。
开启构建缓存的参数：
org.gradle.caching=true默认情况下，Gradle 会把构建缓存放在本地~/.gradle/caches/build-cache-1。对于单机开发，本地缓存已经能带来很大的提升。但团队协作场景，我强烈建议上远程缓存。Gradle 自带的方案是 Gradle Enterprise，商业化的，开销比较大。如果不想引入额外的服务，也可以搭建一个简单的 HTTP 缓存服务，或者直接用 CI 服务器上的共享目录作为缓存层。
关键原理是：Gradle 会对任务的输入做哈希，这个哈希包含任务的所有输入文件内容、参数值、依赖关系等信息。只要输入不变，输出就能复用。所以想让缓存命中率高，任务声明就必须充分。我自己经常遇到的一个问题是：自定义 Task 没声明输入输出，编译结果一变，缓存键就失效，命中率直接掉到谷底。后面第 4 章会给出具体做法。
3.2 配置缓存：把配置阶段的耗时砍掉
如果说构建缓存解决的是“重复干活”的问题，配置缓存解决的就是“重复规划”的问题。开启方式：
org.gradle.configuration-cache=true这个参数的核心行为是：首次构建时正常执行配置脚本，然后把项目配置的结果序列化保存。第二次构建时，Gradle 跳过配置脚本的执行，直接加载序列化结果。对于大型项目，配置阶段从几十秒降到一秒以内是很正常的。
但配置缓存有严格的限制：构建脚本不能随便访问文件系统、不能读取系统属性、不能在脚本顶层写业务逻辑。如果项目里的插件或脚本没有兼容配置缓存，会遇到两类报错：一类是直接失败，比如Configuration cache problems found；另一类是警告，Gradle 会提示哪些操作被禁止了。
遇到兼容性问题，第一反应不要是关掉配置缓存，而是先看是哪个插件不兼容。9.x 下绝大多数主流插件已经兼容了，如果只是几个旧插件，可以考虑升级插件版本。实在不行，可以对特定任务用notCompatibleWithConfigurationCache("原因说明")来排除，至少保证其他任务能享受配置缓存的加速。
3.3 并行执行与守护进程调优
并行执行能直接吃掉多核 CPU 的红利。如果你机器的 CPU 是 8 核 16 线程，而 Gradle 还在串行编译，那就是浪费。参数如下：
org.gradle.parallel=true org.gradle.workers.max=16parallel=true允许不同模块的任务并行执行；workers.max控制的是任务内部并行 worker 的数量，比如编译任务内部会开启多个子进程。这两个参数配合 CPU 核数设置，可以把构建时间压到接近理论下限。
守护进程相关的参数同样至关重要。守护进程就是一个常驻后台的 JVM，承载构建的执行过程。给它足够的堆内存和合理的 GC 参数，能避免构建过程中反复触发 Full GC：
org.gradle.daemon=true org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=1g -XX:+UseParallelGC -Dfile.encoding=UTF-8这里解释一下为什么设置 8GB。大型项目的依赖元数据、任务图、增量状态快照，在内存里占用的空间非常大。默认 1GB 的堆，跑大项目几乎是刚启动就开始 GC。UseParallelGC对构建这种多线程密集的短业务场景比较友好，单次 GC 时间更短。如果你的机器内存充裕，16GB 堆也是值得的，实测 8GB 到 16GB 的边际收益依然存在。
注意：守护进程的内存参数和 IDE 的 Gradle 配置是两套体系。IntelliJ IDEA 里有个单独的 Gradle JVM 设置，默认会用自己的配置。如果 IDE 里构建慢，也要去
Settings -> Build Tools -> Gradle里把 Gradle JVM 和项目 JDK 都设好，并开启 “Build and run using” 为 Gradle 而不是 IntelliJ IDEA，否则 IDE 的增量构建并不会用到我们配置的守护进程参数。
还有一个容易忽略的参数：
org.gradle.vfs.watch=true这是文件系统监听开关，开启后 Gradle 会监听项目目录的文件变化，跳过不必要的文件扫描。实测在大型项目里，这个参数可以让每次构建省下好几秒的扫描时间。默认在部分环境下是关的，建议显式打开。
把上面这些参数汇总到一个完整的gradle.properties，就是：
# Gradle 全局配置 org.gradle.daemon=true org.gradle.parallel=true org.gradle.workers.max=16 org.gradle.caching=true org.gradle.configuration-cache=true org.gradle.configuration-cache.problems=warn org.gradle.vfs.watch=true org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=1g -XX:+UseParallelGC -Dfile.encoding=UTF-8 kotlin.code.style=official这套配置放到项目根目录后，重启 Gradle 守护进程再构建，你会发现增量构建的耗时曲线断崖式下降。
4. 100倍提速的实战配置：从单体到多模块的完整改造
全局参数只是让 Gradle “跑得更快”，真正决定上限的还是项目本身的结构和任务定义。这一章分享我们做多模块改造和依赖管理时的完整配置。
4.1 彻底放弃负面向的脚本写法，改造 settings 文件
很多老项目的 settings.gradle 就是一行行include 'moduleA'，这没问题，但问题出在模块太多后的管理上。你可以用循环生成模块名，减少 include 语句的维护成本：
// settings.gradle.kts rootProject.name = "mega-project" val modules = listOf( "common:core", "common:utils", "service:user", "service:order", "service:payment", "web:admin", "web:api" ) modules.forEach { path -> val moduleName = path.substringAfterLast(':') include(":$path") project(":$path").name = moduleName }这里的思路是：用统一的命名规则管理模块路径，避免手写几十个 include 语句。同时，给每个模块重新设置 name，可以规避模块名冲突。
另外，在 settings 里打开依赖版本集中管理：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven("https://maven.aliyun.com/repository/public") maven("https://maven.aliyun.com/repository/gradle-plugin") mavenCentral() } }FAIL_ON_PROJECT_REPOS这个模式很重要，它会强制所有模块使用 settings 里统一定义的仓库，禁止子项目自己再写 repositories。这避免了“某个模块偷偷配置一个特殊仓库”导致的解析差异和速度下降。
4.2 Version Catalog：固定版本、破除动态依赖
动态依赖版本是构建性能的头号杀手，前面已经提过。彻底解决的方式是使用 Gradle Version Catalog。在gradle/libs.versions.toml里集中定义所有依赖版本：
[versions] spring-boot = "3.5.0" logback = "1.5.6" jackson = "2.18.2" [libraries] spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" } logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" } jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }然后在模块里使用：
dependencies { implementation(libs.spring.boot.starter.web) implementation(libs.jackson.databind) }Version Catalog 带来的好处不止是版本统一。它可以让 Gradle 在解析依赖时少做很多动态查询，直接按固定版本走。对构建提速而言，这比大部分人想象的重要得多。
如果项目体量很大，已经用了动态版本无法一次性改完，可以先用dependencyLocking锁定依赖版本，让 Gradle 只有在 lock 文件变化时才重新解析：
dependencyLocking { lockAllConfigurations() }执行./gradlew dependencies --write-locks会生成gradle.lockfile，之后再构建，Gradle 会直接按锁文件里的版本解析，不再去仓库查询动态版本。
4.3 自定义 Task 的输入输出声明：缓存命中的基本盘
前面反复提到“任务声明不完整会破坏缓存”，这里给一个具体的对比。假设你写了一个自动生成代码的 Task：
// 错误示范：没声明输入输出，缓存完全无法生效 tasks.register("genCode") { doLast { val src = file("src/template") val out = file("build/generated") // 处理逻辑... } }正确做法是显式声明：
// 正确示范 tasks.register<DefaultTask>("genCode") { val src = file("src/template") val out = file("build/generated") inputs.dir(src) outputs.dir(out) doLast { out.deleteRecursively() // 处理逻辑：从 src 生成文件到 out } }加了inputs.dir和outputs.dir之后，Gradle 才能对任务做增量判断和缓存。如果你把模板文件改了，任务会重新执行并更新缓存；模板没变，任务直接跳过。
这里还有一个特别值得注意的坑：Task 内如果读取了系统时间、随机数、环境变量，又没有把这些登记为输入，Gradle 不会认为它有变化，可能直接跳过一次本应重新执行的任务。反过来，如果你把没有变化的文件声明成输入，又会降低缓存命中率。所以任务输入输出的声明逻辑一定要和实际业务严格对齐。
4.4 编译层面的额外提速：注解处理和并行编译
Java 26 对编译器的提升需要配合 Gradle 的--parallel才能真正体现。在此基础上，还有两个参数可以继续压编译时间：
# 开启模块级编译并行 org.gradle.parallel=true # 配置编译 worker 数量，按 CPU 核数调整 org.gradle.workers.max=16另外一个经常被忽视的点是注解处理器。项目用了 Lombok、MapStruct、QueryDSL 这类注解处理器时，Gradle 的增量编译支持是受限的。遇到java: jps 增量注解进程已禁用。部分重新编译的编译结果可能不准确。使用构建进程这类日志，说明注解处理器和增量编译冲突，Gradle 自动禁用了增量编译，退化成全量编译。
解决方案有两个方向。第一个方向是升级插件版本，新版本的 Lombok、MapStruct 对 Gradle 增量编译的兼容性已经大幅改善。第二个方向是如果某个模块确实无法增量编译，可以单独设置：
tasks.withType<JavaCompile>().configureEach { options.compilerArgs.add("-Aproject=${project.name}") }这不会直接解决增量失效，但可以让你通过日志定位是哪个任务禁用了增量编译，再针对性地处理。我在实际项目里看到过很多次：开发同学不知道增量编译被禁用，跑一次构建要两分钟，还以为是正常速度，其实加上一行日志就能发现原因。
5. 常见问题与排查技巧实录：填坑全过程
配置落地之后，不可能一帆风顺。这一章把我们遇到的典型问题和排查思路整理成速查表，并附上几段真实排障过程。
5.1 问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 配置缓存开启后构建报错 | 某个插件或脚本不兼容配置缓存 | 查看报错详情定位插件，升级或排除该任务 |
| 缓存命中率为 0 | Task 未声明输入输出 | 检查自定义 Task，补充@Input/@Output注解 |
| 依赖下载超时，构建失败 | 默认仓库访问慢 | 使用国内镜像仓库，配置networkTimeout |
| 守护进程内存溢出或频繁 Full GC | 默认堆太小 | 调大org.gradle.jvmargs的 Xmx |
| 增量构建始终全量编译 | 注解处理器未兼容 | 升级插件版本或单独处理对应模块 |
| Wrapper 下载卡住 | 访问官方发行包慢 | 修改distributionUrl为国内镜像 |
FLAG_MUTABILITY警告 | 配置缓存检测到脚本副作用 | 检查脚本顶层的文件/网络操作 |
| 构建结果与本地不一致 | 使用了动态版本或脏的本地仓库 | 固定版本；清理本地 maven 缓存 |
| 并行构建偶发死锁 | 依赖关系不明确 | 检查模块间的 task dependency，减少共享输出 |
5.2 从日志定位到根因的一段真实经历
我们线上有一个服务，升级 Gradle 9.4 后，配置缓存始终开启不了，日志里反复出现Configuration cache problems found。一开始我怀疑是某个公司内部插件不兼容，但把所有插件一个个禁用后问题依旧。后来用--info跑了一次构建，才发现是某个模块里有一段历史遗留代码，在脚本顶层直接访问了System.getenv()：
val env = System.getenv("MY_ENV") if (env == "prod") { // 业务逻辑 }配置缓存的机制要求构建脚本必须可序列化，System.getenv()这类动态读取在配置阶段会被视为副作用，直接报错。解决方案是把这段逻辑挪到任务执行阶段，而不是配置阶段。改完之后配置缓存一次性通过，构建时间从 50 秒降到 3 秒左右。
另一个更隐蔽的问题出现在 Jenkins 上。我们的 CI 服务器构建时，每次都是干净的工作区，本地缓存没有命中，构建时间很快就反弹了。后来我们在 Jenkins 任务里挂载了共享的 Gradle 缓存目录，把GRADLE_USER_HOME指向一个持久化的磁盘路径，CI 的构建时间才稳定下来。如果你也在用 Jenkins 做持续集成，记得检查工作区清理策略，最好保留~/.gradle这个目录不被清理，否则你刚刚精心配置的缓存会在每次构建后都被清空。
5.3 Gradle 与 Flutter 项目的一个特殊兼容点
最近有个同事在折腾 Flutter 项目时遇到了一个和 Gradle 相关的报错信息，大致是 “applying flutter's main gradle plugin imperatively using the apply script is not supported”。虽然是移动端项目，但底层原因和构建脚本设计有关：Flutter 的 Gradle 插件需要通过plugins {}块声明式应用，而不是旧式的apply命令式应用。这个报错在 Gradle 9.x 里尤其明显，因为新版本对插件应用方式做了更严格的校验。
如果你要在一台机器上同时开发 Android/Flutter 项目和 Java 后端项目，建议严格区分各自的 Gradle wrapper 版本，不要把全局 Gradle 版本混用。Flutter 项目通常对 Gradle 版本有特定要求，强行用高版本去跑反而会触发各种兼容性报错。
5.4 依赖解析耗时异常的排查思路
如果你的构建时间集中在> Task :dependencies或Resolve dependencies of...这个阶段，说明依赖解析出了问题。第一件事是用--info跑一次，看看哪些仓库响应慢。我们在一次排查中发现，某个模块引用了jcenter()仓库，这个仓库在 Gradle 9 里已经被标注为废弃且访问速度极慢，一查才发现有几个老依赖只存在于 jcenter，没有迁移到 mavenCentral。解决方案是移除jcenter()，把对应依赖的坐标迁移到 mavenCentral 的新版本。
另外，如果项目里大量使用传递依赖，Gradle 可能要做很长的版本冲突解析。可以开启部分模块的transitive = false，或者在 dependencies 块里显式排除无用传递依赖：
implementation(libs.some.lib) { exclude(group = "commons-logging", module = "commons-logging") }这样能减少依赖图的节点数，解析时间会缩短不少。
写在最后的几点实操心得
整套方案落地之后，我个人最大的感受是：构建提速是一个“系统级工程”，不是某一个参数能解决的，需要把项目结构、依赖管理、任务声明、环境配置全部打通。前面给的gradle.properties、镜像配置、Version Catalog、Task 输入输出声明，这四块缺一不可。
如果你刚起步，我建议按这个顺序推进：先配好镜像和 wrapper，解决依赖下载问题；然后打开缓存、并行、守护进程内存；接着处理配置缓存报错；最后再回头清理任务的输入输出声明。每一步都会带来肉眼可见的改善，但只有全部走完，才会出现“百倍提速”的夸张效果。
还有一个小技巧：每次调整配置后，记得执行./gradlew --stop重启守护进程，让新参数生效。别小看这一步，我们团队好几个人调完配置发现没变化，最后都是因为守护进程没重启，还在用旧的 JVM 参数跑。
后续扩展的方向也很多，比如远程构建缓存、构建扫描（Build Scan）、按模块区分 Java Toolchain 等。等核心配置稳定了，可以逐步往这些方向深入。希望对正在折腾大项目构建速度的你有所帮助，少走几步弯路。
