Gradle 创建构建扫描

构建扫描（build scan）是一个中心化并且可以共享的构建记录。这个构建记录通常能够告诉在构建中发生了什么并且为什么会发生。

通过应用构建扫描插件到你的项目中，你可以将你的构建扫描发布到 https://scans.gradle.com 网站中，并且这个服务是免费的。

你将会创建什么

这个指南将会指导你有关构建扫描的特性而且这个不需要你对你现有的脚本进行任何修改。

同时你也将会学习到针对给定项目来扫描所有的构建。可选的方案是，你可以通过修改初始化脚本针对你所有项目来启用构建扫描。

你需要什么来进行创建

• 进入你自己的示例项目，或者你可以从 Gradle 上创建一个示例项目。
• 你的计算机应该需要连上互联网
• 访问你的电子邮件地址
• 大概需要 6 分钟

选择一个示例项目

Gradle 已经创建一个示例可用的 Java 项目，这样你可以用这个项目来示例项目扫描的能力，你如果你需要使用的话，你可以克隆或者下载这个项目。

这个项目的下载地址链接为：https://github.com/gradle/gradle-build-scan-quickstart

如果你希望使用你自己的项目的话，你可以跳过这个步骤。

自动应用构建扫描插件（build scan plugin）

从 Gradle 4.3 版本开始，你可以在你的项目中运行 Gradle 扫描，而不需要任何附加配置。

当你使用命令行选项  --scan 来对项目扫描进行发布的时候，Gradle 将会自动应用需要的插件。在将数据发布到网上之前，在命令行中将会提示要求你接受许可证和协议。

下面为命令行运行时候的系统输出。

这种配置机制能够非常容易的创建临时性的一次性扫描而不需要你在你的构建文件中配置相关的插件。

如果你希望配置更加细力度的配置，你可以在你的构建文件中配置构建扫描插件或者在下面描述的初始化脚本中进行配置。

针对你项目的所有构建启用构建扫描

针对 Gradle 2.x-5.x 版本，你需要应用  com.gradle.build-scan 插件到你的根构建脚本中（build script）。

从 Gradle 6.0 版本开始，你需要应用 com.gradle.enterprise 插件到你的 settings 脚本中。

请参考  Gradle 构建扫描插件文档（Gradle Build Scan plugin docs）中的内容来如何将构建扫描插件应用到你的项目中。

接受许可证协议

为了能够将构建扫描的结果发布到 https://scans.gradle.com 中，你需要接受许可协议。

这个可以在命令行进行发布的时候进行一次性同意协议，你也可以将这个配置到你的 Gradle 构建文件中，这个配置需要配置在 settings.gradle 文件中。

有关的配置如下：

buildScan 代码块允许你配置这个插件。

在这里有 2 个参数你需要输入能够让你的构建自动接收许可协议。有关其他的可以用参数，请参考  Build Scans 用户指南（Build Scans User Manual）页面中的内容。

plugins {
    id "com.gradle.enterprise" version "3.2"
}

发布一个构建扫描

一个构建扫描在命令行中的工具是通过 --scan 命令进行发布的。

在运行  build 任务的时候，你可以选择添加 --scan 选项。当构建任务完成以后将会上传构建数据到  scans.gradle.com 网站上。

在最后，你将会看到已经创建的网站链接，你需要拷贝这个链接到浏览器上打开。

在线访问构建扫描

在你第一次访问提供的构建链接的时候，你需要被要求激活构建扫描。

在你的邮件系统中收到的构建扫描激活链接看起如下图：

按照电子邮件中提供的链接，你单击链接后，你就可以访问到为你创建的构建页面了：

你可以通过页面，访问到有关你这个构建的所有信息，包括有执行的时间，执行的任务，在每一个任务执行所需要的时间，有关测试的所有结果，使用的插件和需要的依赖。

以及包括有有关命令行的开花和其他的更多一些信息。

针对所有构建启用构建扫描（可选）

可选的，你可以通过修改 Gradle 的构建脚本将插件的许可证同意洗液添加到所有的构建中。

具体的修改方法，请参考 https://docs.gradle.com/enterprise/gradle-plugin/#many-projects 页面中的内容。

还有一些更多的构建能力可以添加到脚本中，例如在什么条件下发布构建扫描信息。

有关更多的详细内容，请参考 构建扫描用户手册（Build Scans User Manual）中的内容。

总结

• 在这个指南中，你可能已经学到了：
• 创建一个构建扫描
• 在线查看构建扫描的信息
• 针对所有构建创建一个初始化脚本来启用构建扫描

下一个步骤

有关更多的详细内容，请参考 构建扫描用户手册（Build Scans User Manual）中的内容。

帮助改善这个文档

有一些问题和建议？找到一些拼写错误或者错别字？

与其他所有 Gradle 指南一样，你可以通过创建一个 GitHub 的帮助来帮助我们进行改善。

请  添加一个问题（add an issue）或者为项目 gradle/guides 创建一个 pull request，开发小组将会对你提交的内容作出回应。