📚 课程目录第2章环境准备

环境准备：打好地基才能盖高楼

说实话，很多人一上来就急着看瀑布图，结果发现扫描报告压根打不开。别急，咱先把手头这堆事情搞定。Gradle 的构建扫描说白了就是个“录像机”，但你要先把它插上电。

我刚开始用 Gradle 那会儿，直接拿包管理器装了就开干，结果插件版本死活对不上，浪费了俩小时。所以今天这章，我带你一步一步搭环境。你跟着做，十分钟就能跑出第一个扫描报告。

安装 Gradle —— 别用包管理器，至少我这么觉得

Gradle 有好几种安装方式，我个人习惯用 SDKMAN。为什么？因为它切换版本太方便了。你看我这台电脑上同时挂着 Gradle 7、8 和 9beta，说切就切。

// SDKMAN 安装（推荐）
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install gradle 8.10

如果不想装 SDKMAN，手动下载也行。记住一点：一定要装最新稳定版，别图省事用系统自带的旧版本。构建扫描功能在 5.0 以上才完整，现在都 8.x 了，老版本一堆坑。

// 验证安装
gradle --version

你看到类似这样的输出，就说明安装成了：

------------------------------------------------------------
Gradle 8.10
------------------------------------------------------------

Build time:   2024-09-30 14:00:00 UTC
Revision:     xxxxxx

Kotlin:       1.9.22
Groovy:       3.0.17
Ant:          Apache Ant 1.10.11
JVM:          17.0.8 (Oracle Corporation 17.0.8+9)
OS:           Mac OS X 14.6.1 (aarch64)

小提示：JVM 版本最好 ≥17。Gradle 8.x 对 Java 17 支持最好，跑构建扫描时也更稳定。

启用构建扫描（Build Scan）插件 —— 这才是主角

Gradle 本身不带构建扫描功能，你得装个插件。这个插件叫 com.gradle.build-scan，或者更简单的方式 —— 直接用 Gradle Enterprise 插件。

怎么配？看你的项目用 Groovy 还是 Kotlin DSL。我一般用 Groovy，因为老项目改起来快。

// build.gradle (Groovy DSL)
plugins {
    id 'com.gradle.build-scan' version '3.18.1'
}

buildScan {
    termsOfServiceUrl = 'https://gradle.com/terms-of-service'
    termsOfServiceAgree = 'yes'
}

如果你用的是 settings.gradle.kts，写法也差不多：

// settings.gradle.kts (Kotlin DSL)
plugins {
    id("com.gradle.build-scan") version "3.18.1"
}

buildScan {
    termsOfServiceUrl.set("https://gradle.com/terms-of-service")
    termsOfServiceAgree.set("yes")
}

这里有个坑：我曾经忘记加 termsOfServiceAgree，结果构建直接报错，提示我不同意协议。其实 Gradle 官方要求必须显式同意，除非你用的是企业版。个人开发者直接同意就行，没别的影响。

注意！如果你用的是 Gradle Enterprise 的内部部署版本，插件 ID 和配置方式完全不同。这里只讲公共版的 build-scan 插件。在公司内网跑的话，先问问运维团队。

生成第一个构建扫描报告

插件配好之后，怎么触发扫描？非常简单：在 Gradle 命令后面加上 --scan 参数。

// 运行任意任务，比如 build
gradle build --scan

跑完之后，终端会输出一个 URL，类似这样：

Build scan URL: https://gradle.com/s/abc123def456

点开这个链接，你就看到了第一个构建扫描报告。我第一次打开时，哇，密密麻麻的条条框框，不知道看哪。但别慌，咱们后面几章会逐块拆解。

现在你只需要确认：页面能正常打开，显示的是「Build Scan」字样，而不是 404。能打开，环境就搭好了。

关键检查点：

Gradle 版本 ≥ 5.0（建议用最新 8.x）
build-scan 插件版本与 Gradle 匹配（见官方兼容性表）
终端输出 Build scan URL 且能访问

解读构建扫描首页 —— 先看个大概

扫描报告首页就像汽车的仪表盘，一堆数字和图表。我不要求你现在全看懂，但至少要知道这几个核心指标：

指标	含义	我常关注的点
Total Build Time	整个构建花了多久	超过 5 分钟就要考虑优化了
Task Count	跑了多少个 Task	多了未必好，看看哪些是多余的
Cacheable Tasks	可缓存的 Task 数量	全是 UP-TO-DATE 才是理想状态
Failed Tasks	失败的 Task 数	优先解决，否则后面都是白跑
Configuration Time	初始化配置花了多久	超过 10 秒说明你的 build.gradle 太啰嗦

嗯，看懂这五样，至少知道构建健康不健康了。后面的网络瀑布图、性能热点、依赖分析，都在更深的页面里。咱们留到后面慢慢讲。

这图就是我带你做的这五个步骤。从安装到看懂首页，一条线走下来。