Android 构建提速实战：Gradle 优化的五个关键策略

📰 科技要闻

• 达摩院发布脂肪肝筛查 AI 模型 MAOSS：阿里达摩院推出面向医疗影像的大模型工具，AI+健康领域持续深化落地。

• iPhone 17e 首发体验：苹果新入门机型起售价不变、存储翻倍，加量不加价的策略赢得好评，iOS 生态持续扩张。

• Apple 智能家居屏幕设备推迟至秋季随 iOS 27 发布：传闻中"带屏 HomePod"再度跳票，苹果智能家居战略稳步推进中。

为什么你的 Gradle 构建总是慢得让人抓狂？

Android 工程师日常开发中，等待 Gradle 构建完成几乎是最大的"时间黑洞"之一。一次全量构建动辄 3～5 分钟，CI 流水线上更是轻松突破 10 分钟。时间就这样一点一点流失在进度条里。

本文从实际项目经验出发，系统梳理 Gradle 构建提速的关键策略，帮助你把"等构建"的时间真正省下来。

一、先看清楚慢在哪里

用 Build Scan 定位瓶颈

优化之前，必须先找到真正的慢点。Gradle 官方提供了 Build Scan 工具，可以生成一份详尽的构建报告，包括每个 Task 的耗时、缓存命中率、依赖解析时间等。

在 settings.gradle.kts 中开启：

plugins {
id("com.gradle.enterprise") version "3.16"
}gradleEnterprise {
buildScan {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
publishAlways()
}
}

执行 ./gradlew assembleDebug --scan 后，终端会输出一个可在线查看的 Build Scan 链接，Timeline 视图能直观看出哪些模块、哪些 Task 是耗时大户。

💡 经验：很多团队构建慢的真正原因不是代码编译，而是 kapt 注解处理或某个资源合并 Task，Build Scan 一查便知。

二、配置层面的基础优化

gradle.properties 关键配置

这是成本最低、收益最明显的一步，直接编辑项目根目录的 gradle.properties：

# 开启 Gradle 守护进程（默认已开启）
org.gradle.daemon=true# 开启并行构建
org.gradle.parallel=true# 开启配置缓存（Gradle 8.x 推荐）
org.gradle.configuration-cache=true# 按需配置，只配置需要的模块
org.gradle.configureondemand=true# 堆内存，根据机器配置调整
org.gradle.jvmargs=-Xmx4g -XX:+HeapDumpOnOutOfMemoryError# Kotlin 编译器守护进程内存
kotlin.daemon.jvm.options=-Xmx2g

Configuration Cache 是个大杀器

Gradle 8.x 引入的 Configuration Cache 可以将构建配置阶段的结果缓存起来，下次构建直接跳过配置阶段。对于大型多模块项目，配置阶段可能就要花费 20～40 秒，Configuration Cache 能将这部分时间降到接近 0。

注意：开启 Configuration Cache 后，需要确保所有自定义 Gradle Plugin 和 Task 都是 Configuration Cache 兼容的（不能持有非序列化对象的引用）。可用以下命令检测兼容性：

./gradlew assembleDebug \
--configuration-cache

三、告别 kapt，拥抱 KSP

注解处理（Annotation Processing）是 Android 项目构建慢的重灾区。kapt（Kotlin Annotation Processing Tool）基于 Java APT，需要将 Kotlin 代码先转成 Java Stub，再走 Java 注解处理流程，开销极大。

KSP（Kotlin Symbol Processing） 是 Google 推出的替代方案，直接处理 Kotlin 符号，构建速度比 kapt 快 2～3 倍，且支持增量处理。

迁移 Room 从 kapt 到 KSP

// build.gradle.kts（模块级）
plugins {
// 移除 kapt
// id("kotlin-kapt")// 改为 KSP
id("com.google.devtools.ksp")
}dependencies {
// 将 kapt 改为 ksp
// kapt("androidx.room:room-compiler:2.6.1")
ksp("androidx.room:room-compiler:2.6.1")
}

目前 Room、Hilt、Moshi、Auto Factory 等主流库均已支持 KSP，可以放心迁移。Hilt 同样提供了 KSP 支持，迁移方式类似。

⚠️ 注意：如果项目中 kapt 和 KSP 同时存在（混用不同注解处理器），两套流程都会跑，构建时间不降反升。迁移要彻底，尽量做到"只剩 KSP"。

四、增量编译与构建缓存

本地构建缓存

Gradle 的 Build Cache 功能可以将 Task 的输出缓存下来，当输入不变时直接复用缓存结果，完全跳过 Task 执行。本地缓存默认已开启，只需确认：

# gradle.properties
org.gradle.caching=true

远程构建缓存（CI 提速关键）

本地缓存仅对单台机器有效。在 CI 环境中，每次都是全新容器，本地缓存失效。这时候就需要远程构建缓存——将缓存存储在共享服务器上，所有 CI 节点共享。

// settings.gradle.kts
buildCache {
remote(HttpBuildCache::class) {
url = "https://your-cache-server/cache/"
isPush = System.getenv(
"CI") != null
credentials {
username = "user"
password = "pass"
}
}
}

开启远程缓存后，CI 首次构建生成缓存，后续 PR 构建直接命中缓存，构建时间可缩短 50%～70%。

某中型 Android 项目（40+ 模块）引入远程构建缓存后，CI 构建时间从平均 14 分钟降至 4.5 分钟，全年节省机器时间数千小时。

五、模块化对构建速度的影响

合理的模块化不仅是架构问题，对构建速度影响同样显著：

• 并行编译：模块间依赖关系清晰后，无依赖关系的模块可并行编译，充分利用多核 CPU。
• 增量编译范围缩小：改动某模块只重新编译该模块及其上游依赖，不影响其他模块。
• 缓存命中率提高：稳定的底层模块（utils、network 等）几乎永远命中缓存。

避免"模块化陷阱"

模块化不是越多越好。过度模块化会导致：

• Gradle 配置阶段耗时增加（每个模块都要配置）
• 模块间依赖关系复杂，维护成本上升
• 小模块缓存优势不明显，反而增加调度开销

建议：按业务边界和变更频率划分模块，同一业务域内代码量低于 5000 行不必强行拆分。

六、实测效果参考

以一个中型项目（20 个模块，约 15 万行 Kotlin）为例，采用上述优化后的实测对比：

小结

Gradle 构建优化没有银弹，但有清晰的思路：

1. 用 Build Scan 量化问题，找到真正的瓶颈
2. 用 Configuration Cache + 并行构建 压缩配置和调度开销
3. 用 KSP 替代 kapt，砍掉注解处理开销
4. 用 远程构建缓存 让 CI 不再从零开始
5. 合理模块化，发挥并行与缓存的最大价值

每一分钟的构建时间，都是工程师注意力的成本。把构建速度做上去，是对整个团队效率最直接的投资。

本文为「Android 工程效率」系列文章，后续将持续探讨 CI/CD 流水线搭建、lint/ktlint 代码质量管控、模块化最佳实践等话题，欢迎关注。