📚 课程目录第3章安装和配置Build Scan插件。

安装和配置 Build Scan 插件：给构建过程装上“黑匣子”

说实话，我刚入行做安卓构建优化那会儿，最头疼的就是不知道构建到底慢在哪里。你以为是在编译代码？其实可能是在下载依赖。你以为是在执行任务？其实是配置阶段卡住了。那时候我就在想——要是能给 Gradle 装个“黑匣子”就好了。

嗯，Build Scan 就是这个黑匣子。它能记录每一次构建的完整过程，把每个任务的耗时、输入输出、缓存命中情况全部抓出来。说白了，它就是构建性能的“行车记录仪”。

3.1 为什么非它不可？

你可能觉得“不就是个分析工具吗？用命令行输出也能看啊”。我之前也这么想，直到有一次在一个大项目里排查构建速度——项目有 80 多个模块，构建时间足足 17 分钟。用 --info 跑了一遍，输出信息刷了几万行，看得我眼睛都快瞎了。

而 Build Scan 呢？一个 URL，打开就是 Web 界面，各种瀑布图、耗时排序、缓存命中率一目了然。你想想看，哪个更高效？

核心价值：Build Scan 能回答三个关键问题——

构建到底慢在哪个阶段？（配置阶段 / 任务执行 / 依赖解析等）
哪些任务没有被缓存？（增量编译失效原因）
依赖下载花了多少时间？（网络瓶颈一目了然）

3.2 安装方式有两种，你选哪种？

Build Scan 插件的安装其实有两种常见方式：全项目统一配置和命令行临时启用。我个人习惯用前者，因为团队里统一配置好，大家都不用操心。但如果你只是临时想看某一次构建，用命令行的方式更快。

方式一：在根项目 build.gradle 中声明（推荐）

// 根项目的 build.gradle（或 build.gradle.kts）
plugins {
    id 'com.gradle.build-scan' version '3.17.1'
}

buildScan {
    // 本地开发环境，自动同意条款
    termsOfServiceUrl = 'https://gradle.com/terms-of-service'
    termsOfServiceAgree = 'yes'

    // 发布到 gradle.com（免费版）
    publishAlwaysIf(System.getenv('CI') != null)
    publishAlways()  // 本地也自动发布
}

这里要注意一个坑：publishAlways() 会让每次本地构建都上传 Scan。我在项目中就遇到过，本地调试时顺手跑一下，结果一天上传了几十条，后来被队友吐槽“资源被刷爆了”。所以我建议——本地只按需发布，只在 CI 里用 publishAlwaysIf。

我的个人习惯：开发机上关闭自动发布，只在需要分析性能时手动加上 -Dscan 参数。这样既不影响日常开发，又能随时开抓。

方式二：命令行临时启用（适合快速诊断）

./gradlew clean assembleDebug --scan

加个 --scan 参数，构建完成后会自动生成 Scan 链接。你什么都不用配置，Gradle 会在执行时自动请求 Build Scan 依赖。嗯，这个方法我经常在上线前突击检查时使用，一两秒就能搞定。

3.3 配置要点：别踩这几个坑

配置项	说明	我的建议
`termsOfServiceAgree = 'yes'`	使用 Build Scan 需要同意 Gradle 服务条款	必须配置，否则插件不干活
`publishAlways()`	每次构建都自动发布 Scan	不推荐本地使用，会刷屏
`publishAlwaysIf(condition)`	满足条件才自动发布	推荐在 CI 里用 `System.getenv('CI') != null`
`uploadInBackground = false`	是否后台上传 Scan 数据	调试时设为 `false`，方便看上传状态

我曾经踩过的坑：在 CI 上配置了 publishAlways() 但没有设置 termsOfServiceAgree，结果构建失败了……后来发现是条款同意缺失。记住，两个缺一不可。

3.4 验证是否安装成功

配置完跑一次构建，终端输出末尾能看到类似这样的内容：

Publishing build scan...
https://gradle.com/s/abc123xyz

点开链接，你就能看到完整的构建分析页面了。如果没出现这个链接，检查几点：

插件版本是否写对了？现在最新稳定版是 3.17.x
Gradle 版本是否满足？要求 Gradle 5.0+
是否有网络代理？公司内网经常需要配置代理才能上传

3.5 企业版 vs 免费版，区别在哪？

你可能听说过 Build Scan 有企业版和免费版。说实话，对于个人开发者或小团队，免费版完全够用。我这两年做优化，90% 的场景都用免费版搞定了。区别在于：

免费版：Scan 数据保留 30 天，可以分享链接给别人看，够用
企业版：数据保留更久、可以私有化部署、支持组织管理和策略配置

如果你在公司里做团队级优化，或者想把历史数据保留得更久做趋势分析，那可以考虑企业版。否则，免费版先跑起来再说。

3.6 本章核心流程：安装配置三步走

下面这张图总结了我们从零到一配置 Build Scan 的完整流程——

3.7 实战贴士：别忘了订阅 Scan 生命周期钩子

如果你想把 Build Scan 和 CI 流程深度集成，还可以利用 buildScanPublished 钩子——比如在 Scan 发布后自动把链接发到企业微信或钉钉群。我在公司就是这么干的，每次 CI 构建完成，群里自动弹出 Scan 链接，大家点开就能看到构建报告，效率非常高。

buildScan {
    buildScanPublished { scan ->
        // 发送 scan.getUrl() 到消息通知
        println "📊 Build Scan 已发布: ${scan.url}"
    }
}

好了，安装配置部分就到这里。配置好之后，下一步就是真正开始看 Scan 页面了——嗯，那才是最有意思的部分。等你点开 Scan 链接，看到那张瀑布图的时候，相信你会有和我当年一样的感叹：“原来我项目的构建慢在这里！”