Gradle 构建性能优化全景：瓶颈定位与优化清单

构建性能优化不能从“加缓存”“加内存”“拆模块”这些动作开始，而要先回答一个问题：时间到底花在哪个阶段、哪条图、哪个输入变化上。

Gradle/AGP 构建可以分成初始化、配置、执行三个阶段。初始化决定项目结构，配置创建构建模型和任务图，执行阶段真正跑任务。不同阶段的慢，优化手段完全不同。

可以把构建优化想象成诊断一条生产线。不能因为出货慢就随便买机器，必须先看是排班慢、机器启动慢、某个工位慢，还是返工率太高。

三阶段瓶颈模型

Initialization
  -> settings、included builds、plugin management

Configuration
  -> 评估 build scripts、创建 projects/tasks、计算 variants

Execution
  -> 编译、资源处理、dex、R8、测试、打包

对应优化方向：

执行 ./gradlew help 很有价值：它几乎不需要执行重任务。如果它都慢，瓶颈大概率在初始化或配置期。

先测量，再改动

基础命令：

./gradlew :app:assembleDebug --profile
./gradlew :app:assembleDebug --scan
./gradlew :app:assembleDebug --info

观察维度：

• 配置阶段耗时。
• task timeline 中最长任务。
• 哪些任务没有 UP-TO-DATE 或 FROM-CACHE。
• configuration cache 是否命中。
• 哪些任务被提前 realized。
• Kotlin 编译、资源处理、dex、R8 的占比。

没有数据的优化很容易反向伤害构建。例如盲目拆模块可能减少单次编译范围，也可能引入更多配置成本和依赖解析成本。

最常见的慢源头

大型 Android 工程常见瓶颈：

1. 配置期做 I/O：构建脚本读取文件、网络、Git 命令。
2. 任务 eager creation：tasks.create、all {}、getByName。
3. variant 数量过多：flavor 维度把任务数量乘爆。
4. 注解处理器不可增量：KAPT stub generation 和非增量 processor。
5. 自定义任务无输入输出：每次都跑，且无法缓存。
6. R8 keep 规则过粗：优化空间被锁死。
7. 资源跨模块污染：传递 R 扩大 Java/Kotlin 重编译范围。
8. CI 无远程缓存：每个 job 重复生产同一批产物。

这些问题的共同点是：一个小变化会污染过大的构建子图。

优化优先级

推荐按收益/风险排序：

性能优化不是越多越好。每一项都要用数据验证，不命中缓存的远程缓存只是额外网络开销，不兼容的 configuration cache 会制造更多失败。

Android 特有的优化点

Android 官方建议中的一些关键点，本质都是缩小无效工作：

• 使用非传递 R，避免依赖模块资源符号进入当前模块。
• 使用非 final R，减少常量内联导致的重编译。
• 开发期尽量使用较新设备/API，降低安装和 dex 处理成本。
• 避免在 debug 构建启用 release 级 R8。
• 拆分 data binding 使用范围，减少 kapt 影响面。

这些不是“配置技巧”，而是对构建图污染半径的控制。

建立性能回归防线

优化完成后，还要防回退：

• CI 定期跑代表性构建并记录耗时。
• 对自定义 Gradle 插件加入 TestKit 测试。
• code review 检查配置期 I/O 和 .get()。
• Build Scan 对比改动前后 timeline。
• 对 remote cache 命中率设目标，而不是只看是否开启。

构建性能会随着项目增长自然腐化。没有监控和约束，今天修好的配置期，几周后可能又被一个随手写的脚本读文件拖慢。

工程风险与观测清单

Gradle 构建性能优化全景：瓶颈定位与优化清单 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。

关键风险矩阵

需要持续观测的指标

• 配置阶段耗时是否随模块数量线性或超线性增长。
• 单次本地 debug 构建的关键路径任务是谁。
• CI clean build 与 incremental build 的耗时差距。
• 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
• Configuration Cache 的命中率和失效原因。
• Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
• 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
• 自定义插件是否提前实现了无关任务。
• 构建日志中是否出现未声明输入、重叠输出、deprecated API。
• 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
• 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
• 变更是否影响开发构建、测试构建和发布构建三条路径。

回滚与降级策略

• 构建逻辑变更与业务代码变更分开提交，便于二分定位。
• Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
• 新插件能力先只接入一个低风险模块，再扩大到全工程。
• 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
• 新增插桩、生成代码、资源处理逻辑必须提供开关。
• 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
• 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
• 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

审计问题

1. 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
2. 它是否读取了没有声明为输入的文件、环境变量或系统属性。
3. 它是否在配置阶段执行了本应放到任务动作里的工作。
4. 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
5. 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
6. 它是否把权限、密钥、签名文件路径写进了仓库。
7. 它是否破坏了并发执行，例如多个任务写同一个目录。
8. 它是否能在失败时输出足够日志，帮助定位根因。
9. 它是否能通过一个开关降级，避免阻塞全工程构建。
10. 它是否有最小复现样例或 TestKit/集成测试覆盖。
11. 它是否会让下游模块承担不必要的依赖或任务成本。
12. 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。

反模式清单

• 用 clean 掩盖输入输出声明错误。
• 用 afterEvaluate 修补本可以用 Provider 表达的依赖关系。
• 用动态版本解决依赖冲突，却让构建不可复现。
• 把所有公共配置塞进一个巨型 convention plugin。
• 在 debug 构建默认开启 release 级别的重型优化。
• 在任务动作里读取 project 或全局 configuration。
• 在多个任务中共享同一个临时目录。
• 缓存命中率异常时只重启 CI，不分析 miss reason。
• 把构建扫描链接当作可选附件，而不是性能回归证据。
• 用本地 IDE 成功运行证明 CI 发布链路安全。

最小实操脚本

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Gradle 构建性能优化全景：瓶颈定位与优化清单 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Performance Guide
• Android Optimize Build Speed
• Gradle Build Scan