Gradle Wrapper（Gradle 包裝器）
建議執行任何Gradle構建的方法是在Gradle Wrapper（簡稱爲“ Wrapper”）的幫助下。Wrapper是一個腳本，它調用已聲明版本的Gradle，並在必要時事先下載它。因此，開發人員可以快速啓動並運行Gradle項目，而無需遵循手動安裝過程，從而節省了公司的時間和金錢。
圖1.包裝器工作流程
簡而言之，您將獲得以下好處：
-
在給定的Gradle版本上標準化項目，從而導致更可靠的構建。
-
向不同的用戶和執行環境（例如IDE或Continuous Integration服務器）提供新的Gradle版本就像更改包裝器定義一樣簡單。
那麼它是怎樣工作的？對於用戶而言，通常有三種不同的工作流程：
以下各節將更詳細地說明這些用例。
添加Gradle包裝器
生成Wrapper文件需要在計算機上安裝Gradle運行時的安裝版本，如Installation中所述。幸運的是，生成初始Wrapper文件是一次過程。
每個普通的Gradle構建都帶有一個稱爲的內置任務wrapper。列出任務時，您將可以在“構建安裝程序任務”組下找到列出的任務。執行wrapper任務會在項目目錄中生成必要的Wrapper文件。
運行包裝器任務
$ gradle wrapper
> Task :wrapper
BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed
✨爲了使包裝器文件可用於其他開發人員和執行環境，您需要將其檢入版本控制。包括JAR文件在內的所有包裝程序文件都非常小。期望將JAR文件添加到版本控制中。一些組織不允許項目將二進制文件提交給版本控制。目前，該方法沒有其他選擇。
生成的Wrapper屬性文件，gradle/wrapper/gradle-wrapper.properties存儲有關Gradle分佈的信息。
-
託管Gradle發行版的服務器。
-
Gradle分佈的類型。默認情況下，該
-bin發行版僅包含運行時，但不包含示例代碼和文檔。 -
用於執行構建的Gradle版本。默認情況下，該
wrapper任務會選擇與生成包裝器文件完全相同的Gradle版本。
gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-bin.zip
所有這些方面都可以在以下命令行選項的幫助下配置包裝器文件時進行配置。
--gradle-version
用於下載和執行包裝器的Gradle版本。
--distribution-type
包裝器使用的Gradle分佈類型。可用的選項是bin和all。默認值爲bin。
--gradle-distribution-url
指向Gradle分發ZIP文件的完整URL。使用此選項，--gradle-version並且--distribution-type過時的網址已經包含此信息。如果要在公司網絡中託管Gradle發行版，則此選項非常有價值。
--gradle-distribution-sha256-sum
SHA256哈希和用於驗證下載的Gradle分佈。
讓我們假設以下用例說明了命令行選項的用法。您想生成版本6.0.1的Wrapper，並使用該-all發行版來使您的IDE啓用代碼補全功能並能夠導航到Gradle源代碼。這些要求由以下命令行執行捕獲：
提供包裝任務的選項
$ gradle wrapper --gradle-version 6.0.1 --distribution-type all
> Task :wrapper
BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed
結果，您可以在包裝器屬性文件中找到所需的信息。
示例：生成的分發URL
distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-all.zip
讓我們看一下以下項目佈局，以說明預期的Wrapper文件：
.
├── build.gradle
├── settings.gradle
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat
Gradle項目通常提供build.gradle和settings.gradle文件。包裝程序文件位於項目的gradle目錄和根目錄中。以下列表說明了它們的用途。
gradle-wrapper.jar
包裝器JAR文件，其中包含用於下載Gradle發行版的代碼。
gradle-wrapper.properties
一個屬性文件，負責配置Wrapper運行時行爲，例如與該版本兼容的Gradle版本。請注意，更多常規設置（例如，將包裝器配置爲使用代理）需要進入其他文件。
gradlew， gradlew.bat
一個外殼腳本和一個Windows批處理腳本，用於使用包裝程序執行構建。
您可以繼續使用包裝程序執行構建，而不必安裝Gradle運行時。如果您正在處理的項目不包含那些包裝文件，則需要生成它們。
使用Gradle包裝器
建議始終使用包裝器執行構建，以確保可靠，受控和標準化地執行構建。使用Wrapper看起來幾乎就像通過Gradle安裝運行構建。根據操作系統的不同，您可以運行gradlew或gradlew.bat代替gradle命令。以下控制檯輸出演示了Windows機器上包裝程序在基於Java的項目中的使用。
使用包裝程序批處理文件執行構建
$ 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屬性中的分發URL不變，任何後續的構建調用都將重用現有的本地分發。
✨包裝程序外殼程序腳本和批處理文件位於單項目或多項目Gradle構建的根目錄中。如果要從子項目目錄執行構建，則需要引用這些文件的正確路徑
../../gradlew tasks。
升級Gradle包裝器
項目通常會希望與時俱進並升級其Gradle版本，以從新功能和改進中受益。升級Gradle版本的一種方法是手動更改distributionUrl包裝器屬性文件中的屬性。更好的建議選項是運行wrapper任務並提供目標Gradle版本，如添加Gradle包裝器中所述。使用該wrapper任務可確保對具有該特定Gradle版本的Wrapper Shell腳本或批處理文件所做的任何優化都應用於項目。像往常一樣，您需要將對Wrapper文件的更改提交給版本控制。
使用Gradle wrapper任務生成包裝器，指定版本。默認爲當前版本。升級包裝程序後，可以通過執行來檢查它是否是您期望的版本./gradlew --version。
示例：升級包裝器版本
$ ./gradlew wrapper --gradle-version 6.0.1
BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed
自定義Gradle包裝器
Gradle的大多數用戶對Wrapper的默認運行時行爲感到滿意。但是，組織策略，安全性約束或個人喜好可能需要您更深入地定製包裝器。幸運的是，內置wrapper任務提供了許多選項，可以使運行時行爲符合您的需求。大多數配置選項由基礎任務類型Wrapper公開。
假設您-all每次升級包裝程序時都厭倦了在命令行上定義分發類型。您可以通過重新配置wrapper任務來節省一些鍵盤筆觸。
示例1.定製包裝器任務
Groovy
wrapper {
distributionType = Wrapper.DistributionType.ALL
}
Kotilin
tasks.wrapper {
distributionType = Wrapper.DistributionType.ALL
}
在適當的配置下，運行./gradlew wrapper --gradle-version 6.0.1足以distributionUrl在Wrapper屬性文件中生成一個值，該值將請求-all分發。
生成的分發URL
distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-all.zip
請查閱API文檔，以獲取有關可用配置選項的更多詳細說明。您還可以在Gradle發行版中找到用於配置包裝器的各種示例。
經過身份驗證的Gradle發行版下載
Gradle Wrapper可以使用HTTP基本身份驗證從服務器下載Gradle發行版。這使您可以將Gradle分發託管在受保護的私有服務器上。您可以根據使用情況以兩種不同的方式指定用戶名和密碼：作爲系統屬性或直接嵌入distributionUrl。系統屬性中的憑據優先於中嵌入的憑據distributionUrl。
💡安全警告
HTTP基本身份驗證僅應與
HTTPSURL 一起使用，而不應與普通URL 一起使用HTTP。使用基本身份驗證，用戶憑據以明文形式發送。
使用系統屬性可以.gradle/gradle.properties在用戶主目錄中的文件中完成，也可以通過其他方式進行，請參閱Gradle Configuration Properties。
使用系統屬性指定HTTP基本身份驗證憑據
systemProp.gradle.wrapperUser=username
systemProp.gradle.wrapperPassword=password
distributionUrl在gradle/wrapper/gradle-wrapper.properties文件中將憑據嵌入也可以。請注意，此文件將提交到您的源代碼管理系統中。嵌入的共享憑據distributionUrl僅應在受控環境中使用。
在distributionUrl中指定HTTP基本身份驗證憑據
distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip
可以與已認證或未認證的代理一起使用。有關如何配置使用代理的更多信息，請參見通過代理訪問網絡Wrapper
驗證下載的Gradle發行版
Gradle包裝器可通過SHA-256哈希和比較來驗證下載的Gradle分發。通過防止中間人攻擊者篡改下載的Gradle發行版，提高了針對目標攻擊的安全性。
要啓用此功能，請下載.sha256與要驗證的Gradle發行版關聯的文件。
下載SHA-256文件
您還可以參考Gradle分發校驗和列表。
配置校驗和驗證
將下載的哈希值添加到gradle-wrapper.properties使用distributionSha256Sum屬性或--gradle-distribution-sha256-sum在命令行上使用。
配置SHA-256校驗和驗證
distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10
如果配置的校驗和與在託管發行版的服務器上找到的校驗和不匹配，則Gradle將報告構建失敗。僅當尚未下載已配置的包裝器分發程序時才執行校驗和驗證。
驗證Gradle Wrapper JAR的校驗和
包裝JAR是一個二進制文件，將在開發人員和構建服務器的計算機上執行。與所有此類文件一樣，在執行文件之前，應確保它是可信任的。例如，由於通常將Wrapper JAR檢查到項目的版本控制系統中，因此惡意參與者有可能通過提交或提交似乎只升級Gradle版本的拉取請求來將原始JAR替換爲修改後的JAR。
爲了檢查Wrapper JAR的完整性，Gradle 在 https://services.gradle.org/上與所有 Gradle發行版一起發佈了所有發行版的校驗和（3.3至4.0.2版除外，該版本未生成可再現的JAR）。 您可以通過在主要操作系統之一上運行以下命令來手動驗證Wrapper JAR的校驗和，以確保未被篡改：
在Linux上手動驗證Wrapper JAR的校驗和
$ cd gradle/wrapper
$ curl --location --output gradle-wrapper.jar.sha256 \
https://services.gradle.org/distributions/gradle-6.0.1-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-6.0.1-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-6.0.1-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上生成包裝器JAR的實際校驗和
$ sha256sum gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar
在macOS上生成包裝器JAR的實際校驗和
$ shasum --algorithm=256 gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar
在Windows上生成包裝器JAR的實際校驗和（使用PowerShell）
> (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95
一旦知道了實際的校驗和，請檢查它是否在https://gradle.org/release-checksums/上列出。如果已列出，則您已驗證包裝JAR的完整性。但是，它屬於不同的-可能是較舊的-Gradle版本。在這種情況下，可以安全地wrapper再次運行任務以更新Wrapper JAR，使其與中的Gradle版本匹配gradle/wrapper/gradle-wrapper.properties。
如果頁面上未列出校驗和，則包裝JAR可能來自里程碑，候選發佈版本或每晚生成的版本，或者可能確實不合法。您應該嘗試找出它是如何生成的，但是除非有其他證明，否則應將其視爲不可信的。如果您認爲它是被人爲操縱的，請發送電子郵件至[email protected]告知Gradle團隊。