Android构建优化实战：从10分钟到10秒的Gradle提速指南

自从接手这个 Android 项目的构建之后，我最大的感受就是“等”。改一行文案，等 10 分钟；动一个资源文件，又等 10 分钟；明明只是一个 if 条件调整，却要盯着 Gradle 的进度条发呆。团队里大家私下都在吐槽，每天真正写代码的时间可能只有两三个小时，剩下的时间全在陪编译器“默哀”。后来我痛下决心，花了两周时间专门啃构建优化，把一次全量编译从 10 分钟逐步压到 10 秒级别。这个数据听起来像标题党，但它真的不是概念噱头，而是对构建流程做了系统性拆解之后实打实的结果。这篇博客不聊玄学，不整虚的，把我踩过的坑、用过的配置、验证过的方案全部沉淀下来，给同样被 Android 构建折磨的朋友一条能直接照做的路。

1. 项目概述与目标拆解

1.1 我们到底卡在哪

这个项目是一个历史包袱比较重的业务型 App，模块数量不算夸张，但每个模块之间的依赖关系比较乱。最开始接手时，我的第一反应是“机器性能不够”，于是升级了 CPU、加了内存、换了固态硬盘，结果发现冷启动编译时间确实有一点点改善，但离预期差了十万八千里。真正的问题并不在“跑得慢”的电脑上，而在构建配置本身：Gradle 默认参数没调、增量编译没吃到、依赖解析频繁重复、大量不必要的任务在每次构建中都老实执行一遍。这些因素叠加起来，10 分钟的编译时长就成了常态。

我拿到项目之后做的第一件事不是急着改配置，而是先回答三个问题：第一，这 10 分钟到底花在哪里；第二，哪些时间可以省，哪些时间不能省；第三，优化到什么程度算是“够用”。只有先把这三个问题搞清楚，后面的动作才不会变成瞎折腾。其中最关键的一个认知是：我们需要优化的不是“某一次构建的速度”，而是“整个迭代循环的平均耗时”，这里面的差别非常大。

1.2 优化目标如何量化

很多人一提构建优化就只盯着“全量编译时间”，但实际开发场景中，全量编译并不是最频繁的操作。日常写代码更多是：改一个 Java/Kotlin 文件、加一个资源、调整一下布局，然后点击 Run 看效果。这类操作的耗时，取决于增量编译链路是否足够短。所以我的量化目标最终分成两个：

• 冷启动全量编译：从 10 分钟压到 3 分钟以内，这是阶段目标。
• 改动一行代码后的增量编译：从 1-2 分钟压到 10 秒级别，这是核心目标。

这里有个容易被忽略的点：Android 项目的编译链路比普通 Java 项目长很多，它不只是把 .java/.kt 编译成 class，还要跑资源合并、AAPT2 资源编译、dex 化、打包、签名、安装等一系列任务。任何一个环节出现全量执行，整个耗时就会被拖垮。所以“10 秒”并不是一个不可能的数字，而是意味着我们能够精准地把这些环节中真正需要重跑的部分控制到最小。要做到这一点，首先得有精确的诊断数据，而不是靠感觉去猜。

2. 瓶颈诊断与优化思路

2.1 一份 profile 报告理清时间都去哪了

我强烈建议所有做构建优化的同学，第一步用 Gradle 自带的 profile 功能把构建过程完整记录下来。操作很简单，在项目根目录执行./gradlew assembleDebug --profile，构建结束后会在build/reports/profile目录下生成 HTML 报告，里面会按阶段列出每个任务耗时，也能看到依赖解析、配置阶段、任务执行阶段各自占了多少时间。

我第一次拿到这份报告时，发现一个很扎心的事实：真正花在“编译源码”上的时间只占一部分，大量的耗时被“配置阶段”和“无意义的任务重跑”吃掉了。举个例子，项目里很多模块每次构建都要执行lintVitalRelease、processDebugResources之类的任务，但我们在日常调试时根本用不到它们。这种“任务浪费”比单文件编译慢更值得优先处理，因为它的可优化空间最大。

拿到数据之后，我就做了一个简单的任务耗时排序表，把所有超过 1 秒的任务全部列出来，然后逐个问一个问题：这次构建真的需要执行它吗？如果不需要，就把它跳过；如果需要，再看是否有办法让它执行得更快。这种“按数据逐个击破”的方式，比网上所谓“万能优化脚本”要可靠得多，因为每个项目的耗时结构都不一样。

2.2 常见慢根因清单

根据我的经验，Android 项目构建慢的常见原因基本逃不出这几类：

把这张表打印出来的那一刻，我心里基本有数了。这个项目的配置阶段之所以慢，是因为模块多、依赖图复杂，而且不少模块直接在构建脚本里写了动态版本号，Gradle 每次都要去远程仓库解析。增量编译失效的问题则主要出在自定义注解处理器上，它对增量编译的支持很差，导致 Kotlin 编译器每回都要重新扫描大片源码。资源处理慢则是历史遗留的模块结构问题，后面再单独处理。

2.3 同一条路上的不同走法

同样是构建优化，外界流行的方案其实很多，比如用更高版本的 Gradle、换构建系统、上 Bazel，但这些都属于“大换血”，风险和成本都极高。对一个正在稳定迭代的业务项目来说，最稳妥的方案是“渐进式优化”：在不破坏现有结构的前提下，先把 Gradle 参数调到位，再启用各种缓存和编译增量能力，最后才考虑模块拆分和结构治理。

我的判断标准很简单：哪个改动风险低、收益高，就先做哪个。改gradle.properties里的内存参数和构建开关，属于低风险高收益，可以第一时间做。启用构建缓存和配置缓存，属于中等风险，但收益同样可观。而把模块进行结构性拆分，虽然长期收益最好，但牵涉到代码迁移和回归测试，周期长、坑也多，必须排在最后，不能一上来就动。

这个优先级的确定，直接决定了我们的整体优化路径：先把“壳”的问题解决，再把“骨头”的问题理顺，最后才是“肉”的精细打磨。接下来我讲的每一步实操，基本都遵循这个顺序。

3. 关键优化实操

3.1 gradle.properties 调参：最容易见效的一步

gradle.properties是我在所有优化落地过程中最先动手的文件。很多项目用好几年，这个文件还是默认状态，里面就几行注释，这等于让 Gradle 开着一辆没调过座椅的车跑长途，当然累。我们项目最终沉淀下来的核心配置如下：

org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -Dfile.encoding=UTF-8 org.gradle.parallel=true org.gradle.caching=true org.gradle.configureondemand=true kotlin.incremental=true kotlin.compiler.execution.strategy=in-process android.enableJetifier=true android.useAndroidX=true

这里特别注意org.gradle.jvmargs这一项。很多人以为内存越大越快，于是直接给了 8G 甚至 16G，后果是构建进程频繁 GC，反而拖慢速度。合理的做法是给 Gradle 进程一个“够用但不撑”的内存值，4G 到 6G 往往是最稳的区间。同时MaxMetaspaceSize要单独设置，否则注解处理和 Kotlin 编译这类吃元空间的操作容易 OOM。

org.gradle.parallel=true的作用是让多个模块并行构建，这对多模块项目收益非常明显。但它有一个前提，就是模块之间的依赖关系必须清晰，否则并行反而会导致任务等待和资源争抢。我们项目之前模块依赖纠缠不清，开启并行后反而出现了奇奇怪怪的死锁问题，后来我把依赖理顺，才真正吃到并行构建的红利。configureondemand更像是“按需配置”，只对需要的模块执行构建脚本配置，能省下配置阶段的大量时间，但它同样要求模块边界干净。

3.2 构建缓存与本地缓存：把重复劳动消灭在源头

Gradle 的构建缓存是另一个绕不开的大头。从 3.5 版本开始，构建缓存就能把 task 的输入输出缓存下来，同一份输入在下次构建时直接命中缓存，不再重复执行任务。这个特性最典型的受益场景就是资源处理和 dex 化：只要资源文件没变，processDebugResources的结果就能直接复用。

在我的优化方案里，我在gradle.properties里加了org.gradle.caching=true，然后又保证项目的buildCache配置指向了一个稳定的本地目录。代码修改通常涉及编译任务本身，但资源、Manifest 处理、Dex 打包这些重活在缓存命中时就能飞速跳过。具体配置可以放在项目的build.gradle顶层或 settings 里：

buildCache { local { enabled = true directory = new File(rootDir, "build-cache") removeUnusedEntriesAfterDays = 7 } }

这里要提醒一句，构建缓存听起来很香，但它不是默认就能“命中”的。如果项目里有大量不稳定的 task，比如动态生成文件、时间戳参与输入、输出路径随配置变化，那缓存命中率会低到让人怀疑人生。我的经验是：不要指望一次性把所有 task 都吃到缓存，先把资源类、打包类这些核心重活调到命中，就已经能省下大量时间了。另外，本地缓存目录记得加入.gitignore，千万别提交到版本库里。

3.3 Kotlin 增量编译与注解处理：别让一行改动牵动整个模块

这个项目有一半以上的代码是 Kotlin 写的，Kotlin 编译速度直接决定了增量构建的最坏情况。在 Gradle 里，Kotlin 增量编译默认是开启的，但真正拖后腿的往往是注解处理器。我们项目用了 Room、Dagger 这类需要 kapt 的框架，而 kapt 天生就对增量编译不友好，尤其是 Dagger，它生成的代码量巨大，任何一个伴生对象里的小改都可能触达大面积重新生成。

为了应对这个问题，我的做法分三步走。第一步，确认kapt的增量配置没有被人为关闭，也就是前面gradle.properties里写的kotlin.incremental=true一定要显式声明，因为某些 Gradle 版本对增量支持默认是开着的，但 kapt 的useBuildCache和correctErrorTypes配置也会影响增量效果。第二步，用kotlin.compiler.execution.strategy=in-process把编译放在 Gradle 进程内，省去反复启动 Kotlin daemon 的开销。第三步，也是最推荐的一步，看项目里能不能把部分依赖从 kapt 迁移到 KSP。

KSP 是 Kotlin 官方支持的注解处理方案，它在设计上对增量编译更友好，速度通常能比 kapt 快一倍以上。不过迁移需要改动不少构建脚本和依赖，不是一两周就能完成的。所以我的顺序是：先通过构建缓存和参数调整把现状压到可接受范围，然后再找时间做 KSP 迁移。如果你正在一个新项目里，真的建议一开始就选 KSP，别等历史包袱攒够了再痛苦迁移。

3.4 配置缓存：让“开始构建前”的等待也彻底消失

前文我提过，这个项目的配置阶段经常消耗整次构建 20% 以上的时间。Gradle 为了执行一个构建任务，需要先解析所有模块的构建脚本、计算依赖图、创建任务关系，这套动作每天要被我们反复触发几百次。配置缓存（Configuration Cache）就是把这部分计算结果序列化下来，下次构建直接复用，跳过配置阶段。这真的是一个“让构建从 1 分钟变成 10 秒”级别的优化，但代价是需要项目里的构建脚本满足一定的约束。

启用方式很简单，在gradle.properties里加一行org.gradle.configuration-cache=true，然后重新跑构建。如果你的项目恰好兼容，你会看到日志里出现“Configuration cache entry stored”这样的提示，下次构建配置阶段会大幅缩短。但我必须很直白地说，老项目大概率不会一次就兼容。常见的坑包括：构建脚本里用了System.currentTimeMillis()、读取了环境变量、动态写文件等操作。Gradle 会把不兼容的地方直接报出来，你需要一个个去修，把这些副作用改成惰性计算或者彻底移除。

我们当时花了两三天梳理了所有不兼容点，最折腾的是一个模块在配置阶段做了网络请求判断版本信息，这个操作几乎注定无法兼容配置缓存。最终我们把动态逻辑移到了运行时，或者改成通过任务执行，配置阶段只保留静态信息。改完之后，配置缓存带来的收益非常可观：冷启动构建里配置阶段从十几秒直接压到不到一秒，整个构建提速是很明显的。

3.5 模块与依赖治理：把“结构性浪费”彻底清掉

前几节讲的都是参数和缓存层的优化，属于“把系统调到最佳状态”。但如果项目本身结构有问题，比如模块之间循环依赖、一个大模块里塞了太多无关代码，那再怎么调参都有上限。我们在前面几轮优化之后，构建时间已经降了很多，但离 10 秒目标还有距离。真正让我们完成临门一脚的，是一个看似不起眼却影响巨大的改动：把几个大模块做了懒加载改造和依赖清理。

这个项目原本有一个基础模块，几乎被所有业务模块直接依赖，里面塞了网络、图片、工具类、UI 组件甚至部分业务逻辑。任何代码只要动到这个模块，其他所有依赖它的模块都要重编。我们在分析 profile 时发现，改动频繁地集中在几个业务模块，但因为基础模块被牵连，每次都是整片重编。后来我做了两步：第一步，把里面真正无状态的纯工具类抽成一个core-util模块，这个模块几乎不变，专门吃缓存；第二步，把业务相关的逻辑向外移动到具体业务模块，减少基础模块的职责。这两步做完后，增量编译的命中范围瞬间缩小，单次编译自然就快了。

依赖版本方面，我也把所有动态版本号统一改成了固定版本。动态版本号会让 Gradle 在每次依赖解析时都去仓库检查一遍，虽然不一定重新下载，但解析本身就要消耗网络和 CPU 资源。改成固定版本后，依赖解析阶段几乎不再成为瓶颈。这一步也不是什么高深技术，却是很多团队忽略的“脏活”，效果往往最直接。

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

4.1 缓存命中率低到离谱？先查输入指纹

如果你开了构建缓存但觉得速度没变化，别急着怀疑缓存没用，先确认任务输入是不是稳定的。最常见的“缓存杀手”是构建脚本里有人写了类似def buildTime = new Date()这样的代码，并且这个变量参与了某个任务的输入。因为每次时间都不同，任务输入指纹自然不同，缓存永远不命中。排查方法很简单，跑一次带--info的构建，看到某个任务输出“CACHED”或“FROM-CACHE”的次数占比就能判断。如果资源处理类任务始终在重跑，重点看它的输入是否覆盖了不稳定的文件或属性。

我当时就发现有一个自定义任务把project.buildDir整个目录当作输入，这个目录里全是增量产物，每次构建都会变，相当于整个缓存设计白搭。把输入收敛到真正有意义的源文件之后，缓存命中率立刻恢复正常。这个坑很隐蔽，希望第一次做缓存优化的人能提前避开。

4.2 配置缓存报错，任务却还是能构建：别麻木地关掉它

开启org.gradle.configuration-cache=true之后，项目可能会在某个任务上报出一堆警告，但 Gralde 出于兼容性考虑，有时会退化到“无法缓存配置”的模式，然后继续执行构建。这时候如果只看“构建成功了”就收手，其实配置缓存根本没生效。正确做法是仔细阅读警告内容，定位到具体是哪段构建脚本在配置阶段执行了不该执行的逻辑。

我们的处理流程是：先把所有警告整理成一个清单，然后逐项把不兼容的逻辑改成任务执行时的动作，或者用provider {}延迟求值。修改的过程中可能会出现新的警告，这很正常，构建脚本里的隐含依赖不是一两轮能清干净的。经修改后后，可以连续执行两次构建，第二次看到配置阶段耗时显著下降，才说明配置缓存真正生效。这个动作必须当成一次“专项整改”来做，不能说改两处就放弃。

4.3 并行构建导致的资源争抢与死锁

开启org.gradle.parallel=true后，多模块项目确实能加快整体构建，但如果模块数量很多、CPU 核心线程数设得过大，会反过来变成“先快后慢”：任务并行执行的前半程 CPU 满载，后半程频繁等待磁盘 IO，总时间反而上升。我自己遇到过一种情况，16 核机器上默认并行线程数太大，构建日志里出现了大量的“WAITING”状态，最后我把并行线程数手动限制为 8，整体速度才恢复正常。

死锁问题则多半来自模块之间的循环依赖，只要你用project方式在构建脚本里直接引用其他模块的某些资源或类，就容易埋雷。遇到死锁时，不要只盯着并行参数改，而是要回头理模块依赖图，把环断开。这属于结构问题，参数怎么调都救不了。

4.4 改了资源文件，整个模块还是全量重编

资源文件的改动不及时触发增量，通常是因为 Resources 任务把模块里的res目录或assets目录整体当作输入，任何一个文件变化都会重跑整套资源处理链路。针对这一点，我能想到的有限手段是：把真正需要动态变化的资源隔离到独立模块或独立目录，并减少资源引用层的耦合。对于大部分项目来说，最实用的技巧是避免在res/values中频繁改文件，因为 values 下的翻译和资源项一旦变化，AAPT2 往往会重编大量的资源索引。

如果你的项目里图标、切图这类静态资源很多，可以考虑用androidResources的配置把这些资源单独压缩处理，减少每次构建的扫描范围。说实话，这部分能优化的空间有限，毕竟资源合并本身就是 Android 构建链路里绕不开的一环，但至少可以避免因为“不小心”造成的不必要全量。先把不必要的重跑控制住，资源构建整体的压力就已经小了很多。

5. 从 10 分钟到 10 秒背后的经验沉淀

5.1 本地缓存与团队级缓存的分工

聊完了具体配置，我想再讲讲缓存体系的分层。很多人以为构建优化就是“在本地把代码编译快一点”就完事了，但真实工作中的痛点还包括换台电脑、切换分支、跑 CI 时重新踩同样一遍坑。本地构建缓存解决了单机重复劳动，但你没法保证团队成员各自机器上的缓存一致，也没法保证 CI 机器能复用大家的成果。所以更完善的方案是在团队内部搭建一个远程构建缓存服务，或者至少把 CI 上产出的缓存定期同步到一个共享存储里，让开发者拉下来直接使用。

我当时的项目体量还没到必须搭远程缓存的程度，但我把 CI 构建的缓存目录备份到一台内网服务器的固定位置，新入职同事在首次构建前把这些缓存手动恢复一下，冷启动时间一下就少了一大半。如果你的团队规模更大，直接上 Gradle 的远程缓存（HTTP 缓存）托管会更好，只是需要注意缓存内容的有效性和安全性，别让团队的私有中间产物被无关人员轻易拿到。

5.2 构建配置治理：功夫在配置之外

优化到后来，我有一个越来越明显的感受：构建速度只是结果，前面的配置质量才是根因。项目里的build.gradle如果写得像“屎山代码”，各种动态逻辑、无意义依赖、全局扩展满天飞，那任何参数调整都只是表面粉饰。构建脚本本质上也是代码，应该有代码评审、有依赖治理、有版本锁定，甚至应该定期来一次“构建脚本清理日”。

我把团队的构建脚本调整成了一个相对稳定的状态：所有模块遵守统一的配置模板，版本号集中管理，不必要的插件只在需要它的模块里声明，全局配置尽量少用。这些规则听起来不高深，但它们带来的稳定性非常明显。后来的新成员写编译配置时也更少出错，构建链路自然维持在优化后 10 秒级别。

5.3 一些值得长期坚持的构建习惯

最后分享几个我觉得特别适用的实操习惯，它们不是某一次优化时的临时动作，而是我长期坚持的工作方式：

• 每次重大依赖或 AGP 版本升级后，务必重跑./gradlew clean assembleDebug并记录耗时变化，避免版本升级带来的隐形回退。
• 提交代码前用--profile生成一份构建报告，扫一眼有没有异常耗时的任务，比等人反馈“构建越来越慢”再排查要省力得多。
• 出现“构建变慢”苗头时，先查是不是有人往构建脚本里加了动态时间戳、随机文件名或者临时的println，大多数诡异问题都是这类小改动引起的。
• 在团队文档里沉淀一份“构建优化速查表”，把常见的配置项、命令和排查思路写清楚，不要等新人踩坑后才后悔。

在这个项目之前，我一直觉得“编译优化”是一件门槛很高的事，可能要到系统源码级别才能玩得动。但踩过这些坑之后，我发现对大多数业务项目而言，收益最大的恰恰是那些“细节”和“常识”：合理的内存参数、高质量的缓存命中、干净的模块依赖。把这些做到位，构建速度自然会回馈你。改一行代码等 10 秒，这种爽感真的只有体验过的人才知道，而且一旦体验过，就再也不想回到笨重构建时代了。