执行任何 Gradle 构建的推荐方式是借助 Gradle Wrapper（简称 “Wrapper”）。

Wrapper 是一个脚本，它调用声明的 Gradle 版本，并在必要时预先下载它。因此，开发人员可以快速启动并运行 Gradle 项目。

wrapper workflow

简而言之，您将获得以下好处

  • 将项目标准化到给定的 Gradle 版本，以获得更可靠和稳健的构建。

  • 通过简单的 Wrapper 定义更改，即可为不同的用户配置 Gradle 版本。

  • 通过简单的 Wrapper 定义更改，即可为不同的执行环境（例如，IDE 或持续集成服务器）配置 Gradle 版本。

有三种使用 Wrapper 的方式

  1. 您设置一个新的 Gradle 项目，并添加 Wrapper 到其中。

  2. 您使用 Wrapper 运行项目，该项目已提供 Wrapper。

  3. 您升级 Wrapper 到新的 Gradle 版本。

以下各节将更详细地解释这些用例中的每一个。

添加 Gradle Wrapper

生成 Wrapper 文件需要在您的机器上安装 Gradle 运行时版本，如安装中所述。幸运的是，生成初始 Wrapper 文件是一次性过程。

每个原始 Gradle 构建都带有一个名为 wrapper 的内置 task。当列出 task 时，该 task 列在 “Build Setup tasks” 组下。

执行 wrapper task 会在项目目录中生成必要的 Wrapper 文件

$ gradle wrapper
> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

为了使 Wrapper 文件可供其他开发人员和执行环境使用，您需要将它们检入版本控制。Wrapper 文件（包括 JAR 文件）很小。将 JAR 文件添加到版本控制是预期的。有些组织不允许项目将二进制文件提交到版本控制，并且没有可用的解决方法。

生成的 Wrapper 属性文件 gradle/wrapper/gradle-wrapper.properties 存储有关 Gradle 发行版的信息

  • Gradle 发行版的服务器主机。

  • Gradle 发行版的类型。默认情况下，-bin 发行版仅包含运行时，但不包含示例代码和文档。

  • 用于执行构建的 Gradle 版本。默认情况下，wrapper task 选择用于生成 Wrapper 文件的相同 Gradle 版本。

  • 可选地，下载 Gradle 发行版时使用的 timeout（以毫秒为单位）。

  • 可选地，一个 布尔值，用于设置 发行版 URL 的验证。

以下是 gradle/wrapper/gradle-wrapper.properties 中生成的发行版 URL 的示例

distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip

所有这些方面都可以在生成 Wrapper 文件时使用以下命令行选项进行配置

--gradle-version

用于下载和执行 Wrapper 的 Gradle 版本。生成的发行版 URL 在写入属性文件之前会进行验证。

允许以下标签

--distribution-type

用于 Wrapper 的 Gradle 发行版类型。可用选项为 bin 和 all。默认值为 bin。

--gradle-distribution-url

指向 Gradle 发行版 ZIP 文件的完整 URL。此选项使 --gradle-version 和 --distribution-type 过时，因为 URL 已经包含此信息。如果您想在公司网络内部托管 Gradle 发行版，则此选项很有价值。URL 在写入属性文件之前会进行验证。

--gradle-distribution-sha256-sum

用于验证下载的 Gradle 发行版的 SHA256 哈希值。

--network-timeout

下载 Gradle 发行版时使用的网络超时时间，以毫秒为单位。默认值为 10000。

--no-validate-url

禁用配置的发行版 URL 的验证。

--validate-url

启用配置的发行版 URL 的验证。默认情况下启用。

如果使用 --gradle-version 或 --gradle-distribution-url 配置了发行版 URL，则在 https 方案的情况下，通过发送 HEAD 请求来验证 URL，或者在 file 方案的情况下，通过检查文件是否存在来验证 URL。

让我们假设以下用例来说明命令行选项的使用。您希望使用版本 8.13 生成 Wrapper，并使用 -all 发行版来使您的 IDE 能够启用代码完成并能够导航到 Gradle 源代码。

以下命令行执行捕获了这些要求

$ gradle wrapper --gradle-version 8.13 --distribution-type all
> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

因此，您可以在 Wrapper 属性文件中找到所需的信息（生成的发行版 URL）

distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip

让我们看一下以下项目布局，以说明预期的 Wrapper 文件

.
├── a-subproject
│   └── build.gradle.kts
├── settings.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat
.
├── a-subproject
│   └── build.gradle
├── settings.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

Gradle 项目通常为每个子项目提供一个 settings.gradle(.kts) 文件和一个 build.gradle(.kts) 文件。Wrapper 文件与 gradle 目录和项目的根目录并排放置。

以下列表解释了它们的用途

gradle-wrapper.jar

Wrapper JAR 文件，其中包含用于下载 Gradle 发行版的代码。

gradle-wrapper.properties

负责配置 Wrapper 运行时行为的属性文件，例如与此版本兼容的 Gradle 版本。请注意，更通用的设置，例如配置 Wrapper 以使用代理，需要放入不同的文件。

gradlew, gradlew.bat

用于使用 Wrapper 执行构建的 shell 脚本和 Windows 批处理脚本。

您可以继续使用 Wrapper 执行构建，而无需安装 Gradle 运行时。如果您正在处理的项目不包含这些 Wrapper 文件，则需要生成它们。

使用 Gradle Wrapper

始终建议使用 Wrapper 执行构建，以确保构建的可靠、受控和标准化执行。使用 Wrapper 看起来像使用 Gradle 安装运行构建。根据操作系统，您可以运行 gradlew 或 gradlew.bat 而不是 gradle 命令。

以下控制台输出演示了在 Windows 机器上对基于 Java 的项目使用 Wrapper

$ gradlew.bat build
Downloading https://services.gradle.org/distributions/gradle-5.0-all.zip
.....................................................................................
Unzipping C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0-all.zip to C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-al\ac27o8rbd0ic8ih41or9l32mv
Set executable permissions for: C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0\bin\gradle

BUILD SUCCESSFUL in 12s
1 actionable task: 1 executed

如果 Gradle 发行版在机器上不可用，Wrapper 将下载它并将其存储在本地文件系统中。只要 Gradle 属性文件中的发行版 URL 没有更改，任何后续的构建调用都将重用现有的本地发行版。

Wrapper shell 脚本和批处理文件位于单个或多项目 Gradle 构建的根目录中。如果您想从子项目目录执行构建，例如 ../../gradlew tasks，则需要引用这些文件的正确路径。

升级 Gradle Wrapper

项目通常希望与时俱进，并升级其 Gradle 版本，以从新功能和改进中受益。

升级 Gradle 版本的一种方法是手动更改 Wrapper 的 gradle-wrapper.properties 文件中的 distributionUrl 属性。

更好且推荐的选择是运行 wrapper task，并提供目标 Gradle 版本，如添加 Gradle Wrapper中所述。使用 wrapper task 可确保对该特定 Gradle 版本的 Wrapper shell 脚本或批处理文件进行的任何优化都应用于项目。

与往常一样，您应该将对 Wrapper 文件的更改提交到版本控制。

请注意，运行一次 wrapper task 将仅更新 gradle-wrapper.properties，但保持 wrapper 本身在 gradle-wrapper.jar 中不变。这通常很好，因为即使使用较旧的 wrapper 文件也可以运行新版本的 Gradle。

如果您希望所有 wrapper 文件都完全是最新的，则需要再次运行 wrapper task。

以下命令将 Wrapper 升级到 latest 版本

$ ./gradlew wrapper --gradle-version latest

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

以下命令将 Wrapper 升级到特定版本

$ ./gradlew wrapper --gradle-version 8.13

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

升级 wrapper 后，您可以通过执行 ./gradlew --version 来检查它是否是您期望的版本。

不要忘记再次运行 wrapper task 以下载 Gradle 发行版二进制文件（如果需要）并更新 gradlew 和 gradlew.bat 文件。

自定义 Gradle Wrapper

大多数 Gradle 用户对 Wrapper 的默认运行时行为感到满意。但是，组织策略、安全约束或个人偏好可能要求您更深入地自定义 Wrapper。

幸运的是，内置的 wrapper task 公开了许多选项，可以将运行时行为调整为您的需求。大多数配置选项都由底层 task 类型 Wrapper 公开。

假设您厌倦了每次升级 Wrapper 时都在命令行上定义 -all 发行版类型。您可以通过重新配置 wrapper task 来节省一些键盘敲击。

build.gradle.kts
tasks.wrapper {
    distributionType = Wrapper.DistributionType.ALL
}
build.gradle
tasks.named('wrapper') {
    distributionType = Wrapper.DistributionType.ALL
}

完成配置后，运行 ./gradlew wrapper --gradle-version 8.13 就足以在 Wrapper 属性文件中生成一个 distributionUrl 值，该值将请求 -all 发行版

distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip

查看 API 文档，以获得有关可用配置选项的更详细描述。您还可以在 Gradle 发行版中找到用于配置 Wrapper 的各种示例。

经过身份验证的 Gradle 发行版下载

Gradle Wrapper 可以使用 HTTP 基本身份验证从服务器下载 Gradle 发行版。这使您可以在私有受保护的服务器上托管 Gradle 发行版。

您可以根据您的用例通过两种不同的方式指定用户名和密码：作为系统属性或直接嵌入在 distributionUrl 中。系统属性中的凭据优先于嵌入在 distributionUrl 中的凭据。

HTTP 基本身份验证应仅与 HTTPS URL 一起使用，而不是与纯 HTTP URL 一起使用。使用基本身份验证，用户凭据以明文形式发送。

系统属性可以在用户主目录中的 .gradle/gradle.properties 文件中指定，也可以通过其他方式指定。

要指定 HTTP 基本身份验证凭据，请将以下行添加到系统属性文件

systemProp.gradle.wrapperUser=username
systemProp.gradle.wrapperPassword=password

在 gradle/wrapper/gradle-wrapper.properties 文件中将凭据嵌入到 distributionUrl 中也有效。请注意，此文件要提交到您的源代码控制系统。

嵌入在 distributionUrl 中的共享凭据应仅在受控环境中使用。

要在 distributionUrl 中指定 HTTP 基本身份验证凭据，请添加以下行

distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip

这可以与代理结合使用，无论是否经过身份验证。有关如何配置 Wrapper 以使用代理的更多信息，请参阅通过代理访问 Web。

验证下载的 Gradle 发行版

Gradle Wrapper 允许通过 SHA-256 哈希值比较来验证下载的 Gradle 发行版。这提高了针对目标攻击的安全性，防止中间人攻击者篡改下载的 Gradle 发行版。

要启用此功能，请下载与您要验证的 Gradle 发行版关联的 .sha256 文件。

下载 SHA-256 文件

您可以从稳定版本或候选版本和 nightly 版本下载 .sha256 文件。文件的格式是单行文本，它是相应 zip 文件的 SHA-256 哈希值。

您还可以参考Gradle 发行版校验和列表。

配置校验和验证

使用 distributionSha256Sum 属性将下载的（SHA-256 校验和）哈希值添加到 gradle-wrapper.properties，或在命令行上使用 --gradle-distribution-sha256-sum

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

如果配置的校验和与托管发行版的服务器上找到的校验和不匹配，Gradle 将报告构建失败。仅当配置的 Wrapper 发行版尚未下载时，才执行校验和验证。

如果 gradle-wrapper.properties 包含 distributionSha256Sum，但 task 配置未定义校验和，则 Wrapper task 将失败。当 Gradle 版本未更改时，执行 Wrapper task 会保留 distributionSha256Sum 配置。

验证 Gradle Wrapper JAR 的完整性

Wrapper JAR 是一个二进制文件，将在开发人员和构建服务器的计算机上执行。与所有此类文件一样，您应确保它值得信赖，然后再执行它。

由于 Wrapper JAR 通常检入到项目的版本控制系统中，因此恶意行为者有可能通过提交仅升级 Gradle 版本的拉取请求来替换原始 JAR 为修改后的 JAR。

为了验证 Wrapper JAR 的完整性，Gradle 创建了一个 GitHub Action，它会自动检查拉取请求中的 Wrapper JAR 是否与已知良好校验和列表匹配。

Gradle 还发布了所有版本的校验和（版本 3.3 到 4.0.2 除外，这些版本未生成可重现的 JAR），因此您可以手动验证 Wrapper JAR 的完整性。

在 GitHub 上自动验证 Gradle Wrapper JAR

GitHub Action 与 Gradle 分开发布，因此请查看其文档以了解如何将其应用于您的项目。

手动验证 Gradle Wrapper JAR

您可以手动验证 Wrapper JAR 的校验和，以确保它没有被篡改，方法是在主要操作系统之一上运行以下命令。

在 Linux 上手动验证 Wrapper JAR 的校验和

$ cd gradle/wrapper
$ curl --location --output gradle-wrapper.jar.sha256 \
       https://services.gradle.org/distributions/gradle-{gradleVersion}-wrapper.jar.sha256
$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256
$ sha256sum --check gradle-wrapper.jar.sha256
gradle-wrapper.jar: OK

在 macOS 上手动验证 Wrapper JAR 的校验和

$ cd gradle/wrapper
$ curl --location --output gradle-wrapper.jar.sha256 \
       https://services.gradle.org/distributions/gradle-{gradleVersion}-wrapper.jar.sha256
$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256
$ shasum --check gradle-wrapper.jar.sha256
gradle-wrapper.jar: OK

在 Windows 上手动验证 Wrapper JAR 的校验和（使用 PowerShell）

> $expected = Invoke-RestMethod -Uri https://services.gradle.org/distributions/gradle-8.13-wrapper.jar.sha256
> $actual = (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()
> @{$true = 'OK: Checksum match'; $false = "ERROR: Checksum mismatch!`nExpected: $expected`nActual:   $actual"}[$actual -eq $expected]
OK: Checksum match

解决校验和不匹配问题

如果校验和与您期望的不匹配，则可能是 wrapper task 未使用升级后的 Gradle 发行版执行。

您应该首先检查实际校验和是否与不同的 Gradle 版本匹配。

以下是您可以在主要操作系统上运行以生成 Wrapper JAR 的实际校验和的命令。

在 Linux 上生成 Wrapper JAR 的校验和

$ sha256sum gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

在 macOS 上生成 Wrapper JAR 的实际校验和

$ shasum --algorithm=256 gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

在 Windows 上生成 Wrapper JAR 的实际校验和（使用 PowerShell）

> (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95

一旦您知道实际校验和，请检查它是否列在 https://gradle.org.cn/release-checksums/ 上。如果已列出，则您已验证 Wrapper JAR 的完整性。如果生成 Wrapper JAR 的 Gradle 版本与 gradle/wrapper/gradle-wrapper.properties 中的版本不匹配，则可以安全地再次运行 wrapper task 以更新 Wrapper JAR。

如果校验和未在页面上列出，则 Wrapper JAR 可能来自里程碑版本、候选版本或 nightly 构建，或者可能由 Gradle 3.3 到 4.0.2 生成。尝试找出它是如何生成的，但在另有证明之前将其视为不可信。如果您认为 Wrapper JAR 已被泄露，请发送电子邮件至 security@gradle.com 通知 Gradle 团队。