Gradle Wrapper 参考 - Gradle 构建系统

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

Wrapper 是一个脚本（名为 gradlew 或 gradlew.bat），它会调用声明的 Gradle 版本，必要时会预先下载。您可以使用 Gradle Wrapper 调用 ./gradlew build，而不是使用已安装的 Gradle 运行 gradle build。

Gradle Wrapper 不会作为独立下载项分发，它是使用 gradle wrapper 任务创建的。

使用 Wrapper 有三种方式

添加 Wrapper - 您设置一个新的 Gradle 项目并向其添加 Wrapper。
使用 Wrapper - 您使用已提供 Wrapper 的项目运行。
升级 Wrapper - 您将Wrapper 升级到新的 Gradle 版本。

当使用 Wrapper 而不是已安装的 Gradle 时，您将获得以下好处

将项目标准化到给定的 Gradle 版本，以实现更可靠和健壮的构建。
通过简单的 Wrapper 定义更改，即可为不同的用户提供 Gradle 版本。
通过简单的 Wrapper 定义更改，即可为不同的执行环境（例如，IDE 或持续集成服务器）提供 Gradle 版本。

以下部分将更详细地解释这些用例。

1. 添加 Gradle Wrapper

Gradle Wrapper 不是您下载的东西。

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

每个普通的 Gradle 构建都带有一个名为 wrapper 的内置任务。当列出任务时，该任务列在“构建设置任务”组下。

执行 wrapper 任务会在项目目录中生成必要的 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 任务选择用于生成 Wrapper 文件的相同 Gradle 版本。
可选地，下载 Gradle 分发时使用的超时时间（以毫秒为单位）。
可选地，一个布尔值用于设置分发 URL 的验证。

以下是 gradle/wrapper/gradle-wrapper.properties 中生成的分布 URL 的示例

distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-bin.zip

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

--gradle-version

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

对于以主版本 9 开头的 Gradle 版本，版本可以仅使用主版本或次版本号指定。在这种情况下，将使用与该主版本或次版本匹配的最新正常版本。例如，9 解析为最新的 9.x.y 版本，9.1 解析为最新的 9.1.x 版本。

允许以下标签

--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 方案的情况下会检查文件的存在性。

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

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

$ gradle wrapper --gradle-version {gradleVersion} --distribution-type all

> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

结果是，您可以在 Wrapper 属性文件中找到所需的信息（生成的分布 URL）

distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-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: 包含用于下载 Gradle 分发的代码的 Wrapper JAR 文件。
gradle-wrapper.properties: 一个属性文件，负责配置 Wrapper 运行时行为，例如与此版本兼容的 Gradle 版本。请注意，更通用的设置，如配置 Wrapper 使用代理，需要放在另一个文件中。
gradlew、gradlew.bat: 一个 shell 脚本和一个 Windows 批处理脚本，用于使用 Wrapper 执行构建。

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

2. 使用 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 分发之前没有提供到 GRADLE_USER_HOME，Wrapper 将下载它并将其存储在 GRADLE_USER_HOME 中。只要 Gradle 属性中的分发 URL 不变，任何后续的构建调用都将重用现有的本地分发。

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

3. 升级 Gradle Wrapper

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

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

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

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

请注意，运行 wrapper 任务一次只会更新 gradle-wrapper.properties，但会保持 gradle-wrapper.jar 中的 wrapper 本身不变。这通常没问题，因为即使使用旧的 wrapper 文件，也可以运行新版本的 Gradle。

如果您想让所有 Wrapper 文件都完全最新，您需要第二次运行 wrapper 任务。

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

$ ./gradlew wrapper --gradle-version latest   // MacOs, Linux

$ gradlew.bat wrapper --gradle-version latest // Windows

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

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

$ ./gradlew wrapper --gradle-version {gradleVersion} // MacOs, Linux

$ gradlew.bat wrapper --gradle-version {gradleVersion} // Windows

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

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

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

自定义 Gradle Wrapper

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

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

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

build.gradle.kts

tasks.wrapper {
    distributionType = Wrapper.DistributionType.ALL
}

build.gradle

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

配置到位后，运行 ./gradlew wrapper --gradle-version 9.0.0 足以在 Wrapper 属性文件中生成 distributionUrl 值，该值将请求 -all 分发

distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-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 文件

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

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

配置校验和验证

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

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

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

如果 gradle-wrapper.properties 包含 distributionSha256Sum，但任务配置没有定义校验和，则 Wrapper 任务将失败。当 Gradle 版本不变时，执行 Wrapper 任务会保留 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-{gradleVersion}-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 任务没有与升级后的 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 任务以更新 Wrapper JAR。

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

此页面有帮助吗？