创建构建扫描文档

构建扫描是构建的可共享和集中记录，可提供对发生事件和原因的深入了解。通过将构建扫描插件应用于您的项目，您可以免费发布构建扫描到https://scans.gradle.com。

你会创建什么

本指南将向您介绍如何在不进行任何构建脚本修改的情况下发布构建扫描。您还将学习如何修改构建脚本，以便为给定项目的所有构建启用构建扫描。或者，您还将修改init脚本以启用所有项目的构建扫描。

你需要什么

您可以使用自己的示例项目，也可以使用Gradle提供的示例项目
访问互联网
访问您的电子邮件
大约7分钟

选择一个示例项目

Gradle使您可以使用一个简单的Java项目来演示构建扫描功能。如果您想使用它，请克隆或下载位于https://github.com/gradle/gradle-build-scan-quickstart的存储库。如果您更喜欢使用自己的项目，则可以跳过此步骤。

自动应用构建扫描插件

从Gradle 4.3开始，您可以在构建脚本中启用构建扫描，而无需在构建脚本中进行任何其他配置。使用命令行选项–scan发布构建扫描时，将自动应用所需的构建扫描插件。在构建结束之前，您需要在命令行上接受许可协议。以下控制台输出显示了该行为。
$ ./gradlew build –scan

6秒钟成功完成

您是否接受Gradle Cloud Services许可协议（https://gradle.com/terms-of-service）？[是的，没有]
是
Gradle Cloud Services许可协议已被接受。

发布构建扫描...
https://gradle.com/s/czajmbyg73t62

这种机制可以非常容易地生成临时的一次构建扫描，而无需在构建中配置构建扫描插件。如果您需要更细粒度的配置，则可以按照以下各节中所述，在构建脚本或init脚本中配置构建扫描插件。

在项目的所有版本上启用构建扫描

plugins使用以下内容将块添加到根项目构建脚本文件中：
build.gradle下

plugins {
    id 'com.gradle.build-scan' version '1.13.2' 
}

或build.gradle.kts下

plugins {
    id("com.gradle.build-scan") version "1.13.2" 
}

使用Gradle Plugin Portal上的最新插件版本。
如果您已经有一个plugins块，请始终先安装构建扫描插件。将它添加到任何现有插件下方仍然可以使用，但会遗漏有用的信息。

接受许可协议

为了将构建扫描发布到https://scans.gradle.com，您需要接受许可协议。这可以在发布时通过命令行临时完成，但也可以在您的Gradle构建文件中指定，方法是添加以下部分：
build.gradle下

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

或build.gradle.kts下

buildScan {
    setTermsOfServiceUrl("https://gradle.com/terms-of-service")
    setTermsOfServiceAgree("yes")
}

该buildScan块允许您配置插件。您在此设置接受许可协议所需的两个属性。其他属性可用。有关详细信息，请参阅Build Scans用户手册。

发布构建扫描

使用名为的命令行标志发布构建扫描–scan。
build使用该–scan选项运行任务。构建完成后，将构建数据上传到scans.gradle.com后，您将看到一个链接以查看构建扫描。

$ ./gradlew build --scan

5秒钟成功完成

发布构建扫描...
https://gradle.com/s/47i5oe7dhgz2c

在线访问构建扫描

您第一次关注该链接时，系统会要求您激活创建的构建扫描。
您收到的用于激活构建扫描的电子邮件看起来类似于：

按照电子邮件中提供的链接，您将看到创建的构建扫描。

您现在可以浏览构建扫描中包含的所有信息，包括执行任务所需的时间，构建的每个阶段所需的时间，任何测试的结果，使用的插件和其他依赖关系，使用的任何命令行开关，和更多。

为所有构建启动构建扫描（可选）

您可以避免必须使用Gradle初始化脚本将插件和许可协议添加到每个构建。

~/.gradle/init.d

使用以下内容在目录（代字符表示您的主目录）中创建一个文件：
build.gradle下

initscript {
    repositories {
        gradlePluginPortal()
    }

    dependencies {
        classpath 'com.gradle:build-scan-plugin:1.13.2'
    }
}

rootProject {
    apply plugin: com.gradle.scan.plugin.BuildScanPlugin

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

或build.gradle.kts下

initscript {
    repositories {
        gradlePluginPortal()
    }

    dependencies {
        classpath("com.gradle:build-scan-plugin:1.13.2")
    }
}

rootProject {
    apply<com.gradle.scan.plugin.BuildScanPlugin>()

    configure<com.gradle.scan.plugin.BuildScanExtension> {
        setTermsOfServiceUrl("https://gradle.com/terms-of-service")
        setTermsOfServiceAgree("yes")
    }
}

初始化脚本在必要时下载构建扫描插件并将其应用于每个项目，并接受许可协议。现在，您可以–scan在系统上的任何版本上使用该标志。
您还可以将其他功能添加到脚本中，例如发布扫描信息的条件。有关详细信息，请参阅Build Scans用户手册。

概要

在本指南中，您学习了如何：

生成构建扫描
在线查看构建扫描信息
创建一个init脚本以启用所有构建的构建扫描