Build Scan 制导构建调优：Trace 级别性能问题定位实战
Build Scan 是 Gradle 构建的可观测性报告。它把一次构建的环境、任务时间线、依赖解析、缓存命中、配置性能、失败原因整理成可浏览的诊断页面。
它的价值不是“生成一个漂亮链接”，而是把构建优化从感觉变成证据。没有 scan 的性能讨论，很容易停留在“我觉得 Kotlin 慢”“可能是 R8 慢”“清缓存试试”。
生成 Build Scan
./gradlew :app:assembleDebug --scan
Gradle 会在本地收集构建信息，并在用户确认后发布到 Gradle 托管服务，生成一个私有 URL。它不在本机执行额外构建逻辑，也不会修改构建产物。
对无法发布外部 scan 的企业环境，可以使用 Develocity 或其他内部方案。关键是保留同样的诊断维度。
看 Scan 的顺序
建议按这个顺序阅读：
- Summary：总耗时、失败原因、Gradle/JVM/OS。
- Timeline：最长任务和并行度。
- Performance：配置期、task creation、dependency resolution。
- Build Cache：哪些任务可缓存、是否命中、为什么不缓存。
- Dependencies：依赖解析耗时和仓库访问。
- Tests：测试任务耗时和失败分布。
不要一打开就盯着最长任务。若配置期占比过高，最长执行任务不是第一瓶颈。
Timeline 如何读
Timeline 展示任务执行瀑布：
time ─────────────────────────────>
:core:compileKotlin ███████
:app:mergeResources ████
:app:dexBuilderDebug █████
:app:packageDebug ██
观察三件事：
- 是否有长任务独占关键路径。
- 是否存在大量短任务串行执行。
- 并行度是否被依赖关系限制。
如果一个长任务位于关键路径，优化它收益大；如果耗时分散在大量小任务，可能要减少任务数量或改善配置/缓存。
配置性能页面
配置性能页面能看到哪些任务被 realized。Task Configuration Avoidance 改造时，这里非常关键。
典型问题：
tasks.withType<KotlinCompile> {
// eager configure all existing tasks
}
应改成：
tasks.withType<KotlinCompile>().configureEach {
// lazy configure when task is realized
}
Scan 能告诉你 help 或单个任务构建时，是否仍然提前实现了大量无关任务。
缓存页面如何指导修复
Build Cache 页面会说明任务没有命中的原因：
- Not cacheable：任务类型没有声明可缓存。
- No outputs：任务没有输出。
- Overlapping outputs：多个任务写同一目录。
- Input property changed：某个输入变化。
- Not worth caching：任务太小或被禁用缓存。
修复时不要只追求所有任务都 FROM-CACHE。测试、上传、签名、发布这类带副作用任务本来就不适合缓存。目标是让昂贵且纯净的编译、转换、生成类任务稳定命中。
依赖解析性能
依赖解析慢常见原因：
- 动态版本，例如
1.+。 - SNAPSHOT 或 changing module 缓存策略过短。
- 仓库顺序不合理，频繁打到慢仓库。
- 每个子项目重复声明仓库。
- 插件仓库和依赖仓库混乱。
Build Scan 能显示 repository 访问和依赖解析耗时。修复方向通常是集中仓库声明、禁用 project-level repositories、避免动态版本、使用依赖锁定。
建立对比实验
一次有效优化应有前后对比：
baseline scan: assembleDebug 92s
change: migrate Room kapt -> ksp
after scan: assembleDebug 68s
evidence: kaptGenerateStubs disappeared, compileKotlin reduced
如果没有 scan URL 或本地 profile 记录，优化收益很难复盘，也很难防止未来回退。
工程风险与观测清单
Build Scan 制导构建调优：Trace 级别性能问题定位实战 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。
因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。
关键风险矩阵
| 风险点 | 触发条件 | 直接后果 | 观测方式 | 缓解策略 |
|---|---|---|---|---|
| 输入声明缺失 | 构建逻辑读取未声明文件或环境变量 | UP-TO-DATE 或缓存结果错误 | 使用 --info 和 Build Scan 查看输入变化 |
把所有影响输出的状态建模为 @Input 或 Provider |
| 绝对路径泄漏 | 任务 key 包含本机路径 | CI 与本地缓存无法复用 | 对比不同机器的 cache key 变化 | 使用相对路径敏感性和路径归一化 |
| 配置期副作用 | build script 执行 I/O、Git、网络请求 | 任意命令都变慢，configuration cache 失效 | 执行 help --scan 观察配置期耗时 |
把副作用移动到任务动作并声明输入输出 |
| Variant 污染 | 对所有 variant 注册重型任务 | debug 构建被 release 逻辑拖慢 | 查看 realized tasks 和 task timeline | 使用 selector 精确匹配目标 variant |
| 权限外溢 | 插件或脚本读取 CI secret、用户目录 | 构建不可复现，存在供应链风险 | 审计构建日志和环境变量访问 | 使用最小权限和显式 secret 注入 |
| 并发竞争 | 多个任务写同一输出目录 | 产物互相覆盖或偶发失败 | 检查 overlapping outputs 报告 | 每个任务拥有独立输出目录 |
| 缓存污染 | 不可信分支向远程缓存 push | 全团队复用错误产物 | 统计 remote cache push 来源 | 只允许受信任 CI 写入远程缓存 |
| 回滚困难 | 构建逻辑与业务变更混在一起 | 发布失败时无法快速定位 | 变更审计和构建 scan 对比 | 构建逻辑独立提交、独立验证 |
| 降级缺口 | 新 Gradle/AGP API 无兜底策略 | 升级失败后阻塞全线开发 | 记录兼容矩阵和失败任务 | 保留可回滚版本和迁移开关 |
| 资源释放遗漏 | 自定义任务打开文件句柄或进程未关闭 | Windows/CI 上清理失败或锁文件 | 观察 daemon 日志和文件锁错误 | 使用 Worker API 或 try/finally 释放资源 |
需要持续观测的指标
- 配置阶段耗时是否随模块数量线性或超线性增长。
- 单次本地 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 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
- 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。
最小验证矩阵
| 验证场景 | 命令或动作 | 期望信号 |
|---|---|---|
| 空任务配置成本 | ./gradlew help --scan |
配置期没有无关重任务 |
| 本地增量构建 | 连续执行同一 assemble 任务 | 第二次大量任务 UP-TO-DATE |
| 缓存复用 | 清理输出后启用 build cache | 可缓存任务出现 FROM-CACHE |
| Variant 隔离 | 分别构建 debug/release | 只出现目标 variant 相关任务 |
| CI 可复现 | 干净工作区执行 release 构建 | 不依赖本机隐藏文件 |
| 依赖稳定 | 执行 dependencyInsight | 版本选择可解释，无动态漂移 |
| 配置缓存 | --configuration-cache 连跑两次 |
第二次复用配置缓存 |
| 发布审计 | 记录 scan、mapping、签名信息 | 产物可追溯、可回滚 |
审计问题
- 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
- 它是否读取了没有声明为输入的文件、环境变量或系统属性。
- 它是否在配置阶段执行了本应放到任务动作里的工作。
- 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
- 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
- 它是否把权限、密钥、签名文件路径写进了仓库。
- 它是否破坏了并发执行，例如多个任务写同一个目录。
- 它是否能在失败时输出足够日志，帮助定位根因。
- 它是否能通过一个开关降级，避免阻塞全工程构建。
- 它是否有最小复现样例或 TestKit/集成测试覆盖。
- 它是否会让下游模块承担不必要的依赖或任务成本。
- 它是否能在升级 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
这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Build Scan 制导构建调优：Trace 级别性能问题定位实战 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。