先声明一下这篇不是给“构建不到一分钟就嫌慢”的小项目看的。百万行代码、两三百个模块的仓库构建一次十几分钟甚至半个多小时那种痛只有真正经历过的人懂。这篇文章会从一个真实的大型项目改造过程出发把配置阶段、任务执行、依赖解析、构建缓存和守护进程这些优化点逐个拆开讲清楚全是能直接抄作业的配置和思路。我接手过一个大概 180 万行代码、260 多个模块的 Java/Kotlin 混合项目。刚接手的时候本地执行一次干净的build大概要 21 分钟热启动的增量构建也要 5 到 8 分钟。最离谱的是很多时候你只是改了一个字符串保存、编译、跑测试、打包一上午就过去了。最开始我也想过“是不是电脑不行”后来换了 32G 内存的机器发现只快了两分钟——问题根本不在硬件上而是在 Gradle 的配置和执行方式上。这篇文章我会把整个优化过程按阶段拆开写。每个阶段都会说明为什么这么做、怎么落地、以及我踩过的坑。如果你手里的项目也是这种体量大概率能直接复用这套思路。1. 面对百万行代码项目先弄清“慢”发生在哪个阶段很多团队一提到 Gradle 慢第一反应就是加内存、上 SSD、调并行。这些手段有用但如果方向不对加再多资源也是白搭。优化之前必须先回答一个问题构建的 20 分钟究竟花在了哪个阶段Gradle 的一次完整构建可以粗略分成三个阶段阶段主要工作常见特征初始化阶段解析 settings.gradle确定项目结构时间通常很短但多模块项目会累加配置阶段执行所有 build.gradle 脚本构建任务图脚本里写什么这一步就干什么执行阶段真正执行任务编译、打包、测试最耗时但也是最容易优化的一环注意配置阶段这个词它跟编译没有直接关系但很多大型项目的慢恰恰就慢在这里。因为 Gradle 的配置阶段会把所有模块的构建脚本全部执行一遍哪怕你只想编译其中一个模块。一个 260 模块的项目如果每个模块的 build.gradle 里都有一堆耗时操作配置阶段就会非常痛苦。先诊断再动手。诊断工具我推荐两个./gradlew build --profile生成一份 HTML 报告能精确看到每个阶段和每个任务消耗的时间。./gradlew build --scan生成在线构建扫描信息更全能看到依赖解析时间、任务缓存命中率等适合跨团队分享和对比。我把这两样跑完之后发现了一组非常典型的数据配置阶段4 分 20 秒占总耗时的大约 35%依赖解析1 分 10 秒任务执行11 分 30 秒其他初始化、生成报告等约 1 分钟配置阶段 4 分多钟这个数字是极不正常的。它意味着每次你运行任何任务哪怕只是gradlew help都得先白等 4 分钟。优化配置阶段就成了第一个突破口。这里有个判断经验如果一个项目配置阶段超过总耗时 20%先不要碰编译参数先把配置阶段压缩下来。因为配置阶段是纯开销不产生任何有价值的产物而且它拖累的是每一次构建增量构建也不例外。2. 配置阶段把脚本里的无效开销一点点抠掉配置阶段的本质是执行构建脚本构建脚本的任务是构建任务图。问题出在很多人在脚本里写的逻辑远超“构建任务图”所需。我看到过不少项目在配置阶段做文件扫描、动态生成资源、甚至访问网络接口这些操作每个模块来一遍项目一多就完蛋。2.1 任务惰性注册别让“创建任务”变成“执行任务”Gradle 提供了两种注册任务的方式// 旧写法配置阶段立即创建并配置任务 tasks.create(generateConfig) { doLast { // 执行逻辑 } // 配置逻辑 } // 新写法惰性注册只有任务真正需要执行时才创建 tasks.register(generateConfig) { doLast { // 执行逻辑 } }看起来区别不大但在几百个模块的场景下差距是巨大的。tasks.create在配置阶段就会创建任务实例并执行配置块里的代码tasks.register只是登记一个名字等执行阶段真正需要这个任务时才去实例化。我当时做了一件事把项目里所有tasks.create、task foo { }改成tasks.register这是个机械但有效的操作。顺手还把 build.gradle 里大量doFirst、doLast外层的无谓配置代码清理了一遍。这一轮下来配置阶段从 4 分 20 秒降到了 3 分左右。这个改动最麻烦的地方在于任务依赖关系如果脚本里有foo.dependsOn bar这种写法而bar还未注册会直接报错。所以建议从一个模块试点开始不要一口气全量替换。2.2 别让 afterEvaluate 和跨项目配置失控afterEvaluate在大型项目里是大坑。它会在模块配置完成后回调常用于插件间的配合。问题是一旦用多回调的执行顺序会非常脆弱而且它强制 Gradle 在配置阶段结束前把所有模块的配置都攒着间接拖慢配置。还有一种常见的低效写法subprojects { // 每个子项目在这里做一堆事 }subprojects、allprojects本身不一定是坏事但块里的逻辑如果不是所有子项目都需要的就应该拆出去按需应用。我在改造时把公共配置拆成了单独的 convention 插件Gradle 官方文档叫 convention plugins每个模块只需要在自己的 build.gradle 里显式id xxx.conventions。这样既清爽又省了配置时间。2.3 配置缓存把配置阶段整个“保存”下来配置阶段优化的终极武器是 Configuration Cache。Gradle 8.x 已经默认支持它的原理是把配置阶段产出结果序列化存起来下次构建只要输入没变就直接从缓存恢复配置跳过脚本执行。配置缓存对大型项目的效果立竿见影。开启方式org.gradle.configuration-cachetrue如果遇到兼容性问题可以先开“警告模式”看看org.gradle.configuration-cachetrue org.gradle.configuration-cache.problemswarn配置缓存对脚本有严格要求构造阶段不允许执行任意代码、访问文件系统、访问系统属性等。所以如果项目里有很多在脚本顶层做文件操作的地方第一次开启时会报一堆错误。别慌这些错误恰恰暴露了哪些脚本逻辑本不该写进配置阶段。我项目里遇到的典型问题包括配置阶段读取 local.properties 判断环境导致缓存键漂移某些插件在配置阶段动态生成版本号自定义任务类里直接new File(...)但没有声明为输入。花了一周时间把这些问题清理掉配置阶段直接从 3 分钟降到了 20 秒以内。这个收益是压倒性的值得为它投入时间。2.4 多项目复用用复合构建替代“一次性加载全部模块”如果你的项目有多个 Git 仓库但构建时却靠 include 把其他仓库也拉进同一个构建那么每个仓库的配置都会叠加到配置阶段里。这种情况我建议试试 Composite Build复合构建。复合构建的思路是每个仓库独立构建但可以作为一个整体协同Gradle 会在需要时自动使用对应仓库的构建输出。相比把所有仓库塞进一个构建它能让各仓库的配置逻辑隔离某次只改一个仓库时不需要重新配置所有仓库。不过复合构建需要团队在工程结构上配合不是改一行配置就能迁移的具体收益也依赖项目情况。对于多模块单仓库的项目优化配置阶段更优先的是前面两条。3. 任务执行阶段让“没变的输入”真的不重跑配置阶段解决完之后大头就轮到执行阶段了。执行阶段的优化核心只有一句话已经算过的东西不要重复算。3.1 up-to-date 检查是怎么工作的Gradle 的每个任务都有一组输入源文件、依赖、参数和输出产物文件。执行前Gradle 会计算输入的哈希值再和上次构建记录的哈希值对比。如果一致且输出文件还在就认为任务“是最新的”直接跳过。这套机制本身很聪明但前提是你把输入和输出声明对了。很多自定义任务只写了任务逻辑没有加输入输出注解Gradle 就只能每次都执行。一个典型的自定义任务abstract class MergeJsonTask extends DefaultTask { InputFiles abstract ConfigurableFileCollection getInputFiles() OutputFile abstract RegularFileProperty getOutputFile() TaskAction void merge() { // 合并逻辑 } }加了InputFiles和OutputFile之后Gradle 才能执行缓存判断。如果是InputFiles目录内容建议配合SkipWhenEmpty和Incremental增量变更时只处理变更文件避免整个输入目录反复读取。3.2 常见失效原因绝对路径、时间戳和随机输出花大力气声明了输入输出却发现缓存一直不命中通常逃不出这几个原因失效原因表现解决办法输入包含绝对路径换个机器或换个人缓存就失效使用相对路径或project.layout输出带时间戳每次生成产物内容都不同输出文件内容别写构建时间可用固定值构建过程写入临时文件到项目目录输入集合意外变化临时文件写到build/目录依赖了动态版本每次解析都变固定版本号或用锁文件注解处理器生成随机顺序输出顺序不稳定对生成文件排序后再输出我项目里曾经有个代码生成任务输出目录里包含了构建时间导致所有下游编译任务每次都全量编译。排查到的时候那个任务的缓存命中率是 0%改了之后整个编译缓存命中率一下子上去了。3.3 并行执行与 Worker API多模块构建的并行执行配置一行就能开org.gradle.paralleltrue但并行不是万能药如果项目本身单模块编译并行帮不上忙。更重要的是单模块内部的并行化要利用 Gradle Worker API 把你的自定义任务拆成多个可并行的工作单元。比如一个处理上千个文件的转换任务串行处理大约需要 5 分钟改用WorkerExecutor把文件分批提交按 CPU 核心数并行处理后时间能压低到 1 分半左右。对于少量超大任务的流水线型构建这个优化非常明显。还有个容易被忽略的点org.gradle.workers.max参数把并行工作线程数写死可以避免和机器上其他进程抢资源。我一般会根据 CI 机器规格设置一个合理值比如 8 核机器设置成 6。3.4 给编译器留点空间Kotlin/Java 编译参数Java 编译默认是 JVM 内进程Kotlin 编译默认走 Kotlin daemon。大型项目里这两块的耗时占比通常是最高的。对 Java 编译重点是保证尽可能多的增量编译tasks.withType(JavaCompile).configureEach { options.incremental true options.compilerArgs -parameters }对 Kotlin优先确保用较新的 Kotlin 插件版本低版本 Kotlin 编译性能差异很大。而且kotlin.compiler.execution.strategyin-process可以省掉 daemon 进程间通信的开销但会让 Gradle 守护进程更吃内存要结合机器配置权衡。还有一类项目用了 kapt 处理注解这就是个性能黑洞。kapt 会为每个模块启动独立注解处理任务比普通编译慢好几倍。现在一般建议能迁移到 Kotlin Symbol ProcessingKSP的就迁移提前给 kapt 开启 worker 隔离和缓存别让它默认跑在主守护进程里。4. 依赖解析每次构建都要联网的隐藏开销依赖解析在构建耗时里通常不是最大头但它是每次构建都会发生的而且增量构建里占比会被放大。我在那个项目里做过一个实验清空本地依赖缓存后第一次跑构建光下载依赖就花了 40 分钟。虽然这是极端情况但也说明依赖这块的基建不能忽视。4.1 固定版本别用动态版本和固定版本不加锁构建脚本里最常见的写法是implementation com.example:lib:1.2.或implementation com.example:lib:latest.release。动态版本每次构建都可能解析到新版本Gradle 必须在仓库里查询元数据这个查询既有网络开销又会破坏缓存确定性。正确做法是使用精确版本号。如果依赖特别多、维版本很痛苦可以用 Gradle 的依赖锁定功能在settings.gradle里启用dependencyLocking { lockAllConfigurations() }然后执行一次gradlew dependencies --write-locks生成锁文件。之后构建用的版本完全由锁文件决定解析速度快了一大截缓存稳定性也更好。4.2 内部代理仓库解决反复下载、超时问题只要项目用到开源依赖就得从外部仓库下载。在大型团队里每个人本地都从外网拉同一份依赖不仅浪费时间还经常因为网络抖动导致构建失败。最稳妥的方案是在企业内部搭建一个制品代理仓库Nexus 或 Artifactory 都行把常用的中央仓库、插件仓库都代理一遍。Gradle 这边配置好地址之后团队所有成员和 CI 都指向内部仓库依赖下过一次就缓存住了速度能快好几倍还能避免各种网络超时问题。一个比较干净的settings.gradle仓库配置pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() } } dependencyResolutionManagement { repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } }注意一点代理仓库配置好之后团队内部的依赖变更也应当发布到同一个仓库里不然会出现“本地包找不到”的问题。如果不能用内网仓库至少也要让 Gradle 把依赖缓存保留得久一点别手动去清~/.gradle/caches。4.3 离线模式与依赖缓存健康对稳定的 CI 链路可以考虑在构建命令后加--offline强制 Gradle 只用本地缓存。这样构建完全不受网络波动影响速度也更稳定。当然前提是依赖已经提前下载好通常 CI 首次构建时用在线模式预热缓存之后的任务都用离线模式就可以了。依赖缓存本身也可能“坏掉”最常见的报错就是 Gradle dependency cache may be corrupt。一般处理方式是先定位是哪个仓库的缓存坏了再针对性删除对应的缓存目录不要一上来就删整个~/.gradle/caches否则所有依赖都得重新下又白等一次。5. 构建缓存一次计算处处复用构建缓存和 up-to-date 检查是两回事。up-to-date 检查只能让你本机的同一份输入不重跑构建缓存则是把任务的输出按输入哈希打标签存起来换一台机器、换一个人、甚至换一个分支只要输入一致就能直接下载产物跳过任务执行。5.1 本地构建缓存开启方式org.gradle.cachingtrue开启后每次构建任务执行完毕Gradle 会把输出打包存到本机~/.gradle/caches/build-cache-1里。下次构建其他模块如果有相同输入的任务就能直接复用。本地缓存对“切分支”和“回滚”场景效果明显。之前团队切换分支后由于文件变化所有模块几乎都要重编开了缓存后切回之前构建过的分支很多模块直接命中构建时间从 7 分钟降到 2 分钟。5.2 远程构建缓存对团队来说远程构建缓存的价值更大。思路是搭建一个共享的构建缓存服务CI 构建完把产物上传开发者本地构建时如果输入命中 CI 的缓存就直接拉取产物不用在自己电脑上重新编译。自建远程缓存可以直接用 Gradle 开源的 Build Cache Node部署个 Docker 容器就行。配置也简单org.gradle.cachingtrue org.gradle.caching.httptrue然后在settings.gradle里指定buildCache { remote(HttpBuildCache) { url uri(https://build-cache.example.com/cache/) allowUntrustedServer false } }远程缓存的关键是命中率。命中率上不去缓存服务形同虚设。提示开启远程构建缓存前一定要先确保项目构建是可复现的。如果任务输出里有随机性、时间戳、绝对路径远程缓存的产物可能会污染整个团队所以先解决 3.2 节那些问题再上远程缓存。5.3 哪些任务值得缓存缓存也不是所有任务都适合。一般重点缓存编译任务、打包任务、静态分析任务。像发布任务、网络请求任务这种不应该开缓存可能产生副作用。自定义任务若要支持构建缓存需要加CacheableTask注解并且保证输入输出声明完整。没加注解之前任务只是不会缓存不会报错加了之后如果声明不完全缓存命中时可能会拿到错误产物所以加注解前要仔细检查。6. 守护进程与 JVM 参数榨干最后几个百分点前面把配置阶段、执行阶段、依赖、缓存都调完之后还有一类收益往往被忽略就是对 Gradle 守护进程本身进行调优。守护进程是 Gradle 执行构建的常驻后台进程它的健康程度直接影响构建稳定性。6.1 堆和元空间设置Gradle 默认的 JVM 参数在 gradle.properties 里配置org.gradle.jvmargs-Xmx4g -XX:MaxMetaspaceSize1g -XX:UseParallelGC对于大型项目4G 堆是起步我自己的项目最终调到了-Xmx6g -XX:MaxMetaspaceSize2g。Metaspace 特别容易被忽略插件加载、注解处理都需要额外的元空间太小会频繁触发 Full GC构建速度肉眼可见地下降。6.2 GC 选择构建场景别迷信 G1很多人习惯用监控工具推荐的 G1 垃圾收集器但 Gradle 构建场景有自己的特点任务执行期间会创建大量短生命周期对象堆内存波动很大你需要的是高吞吐而不是低延迟。-XX:UseParallelGC在这种场景下通常比 G1 更合适。数据支撑我之前对比过两台配置完全一样的机器一台用 G1、一台用 Parallel GC同样的清理全量构建Parallel GC 大约快了 12%。虽然不是特别夸张但在大项目上也是几分钟的差距。如果构建时观察到长时间的 GC 停顿可以开 GC 日志看org.gradle.jvmargs-Xlog:gc*:filegc.log:time然后去分析日志里 Full GC 的频率和耗时。如果 Full GC 频繁优先加大堆而不是换 GC。6.3 守护进程数量与稳定性大型项目容易遇到一个问题多个 Gradle 项目目录各自启动了自己的守护进程把内存占满然后旧的守护进程被系统杀掉之后构建又要重新初始化等于一切推倒重来。针对这种情况建议统一 Gradle 版本Gradle 版本不一致一定会启动多个守护进程使用~/.gradle/gradle.properties里的org.gradle.daemon.idletimeout控制空闲守护进程回收时间默认 3 小时太长可以调到 30 分钟在 CI 上构建完主动停掉守护进程避免占着内存。排查守护进程状态可以用gradlew --status能列出所有运行中的守护进程、它们的 JVM 版本和最近使用的项目。如果看到很多不同版本的守护进程大概率是某些人的 Gradle wrapper 没统一。7. 这次优化里最容易被忽略的三个细节最后分享一下在优化过程中反复吃过的亏都是在文档里不容易找到的细节。第一个构建脚本里的字符串操作和文件操作往往比想象中贵。我当时排查过一段脚本它在配置阶段用JsonSlurper解析 API 描述文件来动态生成任务参数单个模块不慢但 260 个模块叠起来就是一分多钟。解决方案是把这个逻辑放进doFirst或者任务执行时执行而不是配置阶段。第二个别频繁清理build/目录。有些项目为了“保证干净”在 CI 脚本里每次都clean。如果搭配了构建缓存其实没必要全量 clean除非你真的要验证从零构建。频繁 clean 会破坏增量构建和本地缓存等于把前面所有优化全部抵消。第三个构建优化是一个持续过程不是一次性的。我建议每个季度看一次构建扫描观察任务耗时分布和缓存命中率的变化。特别是项目在增长、依赖在增加的时候配置阶段占比会重新恶化。我每次接手新项目或者大版本升级 Gradle 后都会重新跑一轮--scan看看有没有新出现的性能拐点。关于 Gradle 版本升级我也建议不要太保守。Gradle 8 以上的配置缓存、更快的文件系统监控、更优的依赖解析对大型项目都是实打实的提升。但升级前一定要先在 CI 上完整跑一遍确认没有插件兼容性问题再推给团队。这个过程中的收获往往比单纯调参数还要大。