將您的建置從 Gradle 5.x 升級至 6.0

自Gradle 3.4以來，Java 生態系統外掛程式中已不建議使用 compile 和 runtime 配置。

這些配置用於編譯和執行來自 main 來源集中的程式碼。其他來源集會建立類似的配置（例如 test 來源集的 testCompile 和 testRuntime），也不應使用。implementation、api、compileOnly 和 runtimeOnly 配置應用於宣告相依性，而 compileClasspath 和 runtimeClasspath 配置應用於解析相依性。請參閱這些配置之間的關係。

uploadArchives 任務和 maven 外掛程式已棄用。

使用者應使用 maven-publish 或 ivy-publish 外掛程式遷移至 Gradle 的發布系統。這些外掛程式自 Gradle 4.8 以來已穩定。

發布系統也是確保發布 Gradle 模組中繼資料 的唯一方法。

當 Gradle 偵測到任務定義問題（例如錯誤定義的輸入或輸出）時，它會在主控台上顯示以下訊息

棄用警告會顯示在每個建置的建置掃描中，無論使用何種命令列切換器。

當使用 --warning-mode all 執行建置時，將會顯示個別警告

如果您擁有相關任務的程式碼，您可以透過遵循建議來修正它們。您也可以使用 --stacktrace 來查看每個警告的程式碼來源。

否則，您需要向相關任務或外掛程式的維護者回報問題。

在 Gradle 5.4 中，我們為實作增量任務引入了新的 API：InputChanges。基於 IncrementalTaskInputs 的舊版 API 已棄用。

在第一級相依性上使用 force = true 強制相依性版本已棄用。

強制同時存在語意和排序問題，可以透過使用嚴格版本約束來避免。

在 Gradle 5.0 中，我們移除了 --no-search-upward CLI 參數。

StartParameter 中相關的 API（例如 isSearchUpwards()）現在已棄用。

這些方法目前無法如預期運作，因為在建置開始後永遠不會呼叫回呼。

棄用這些方法是為了避免混淆。

預設情況下，封存任務 Tar 和 Zip 允許在建立的封存檔中存在多個相同路徑的項目。這可能會導致「嚴重無效的 zip 檔案」，可能會觸發 zip 炸彈偵測。

為了防止意外發生，在建立封存檔時遇到重複項目現在會產生棄用訊息，並將在 Gradle 7.0 開始使建置失敗。

Copy 任務也很樂意將多個具有相同相對路徑的來源複製到目的地目錄。此行為也已棄用。

如果您想要允許重複項目，您可以明確指定

Gradle 建置由目前或父目錄中的 settings.gradle[.kts] 檔案定義。在沒有設定檔的情況下，Gradle 建置是未定義的，並將發出棄用警告。

在 Gradle 7.0 中，Gradle 將僅允許您使用未定義的建置來調用 init 任務或診斷命令列標誌，例如 --version。

一旦專案被評估，Gradle 會忽略所有傳遞給 Project#afterEvaluate 的配置，並發出棄用警告。這種情況將在 Gradle 7.0 中變成錯誤。

以下捆綁的外掛程式從未發布，將在 Gradle 的下一個主要版本中移除

其中某些外掛程式可能在外掛程式入口網站上有替代品。

Gradle 6.0 支援 Android Gradle Plugin 版本 3.4 和更新版本。

對於 Gradle 6，建置掃描外掛程式的使用必須替換為 Develocity 外掛程式。這也需要變更外掛程式的套用方式。請參閱https://gradle.com/help/gradle-6-build-scan-plugin 以取得更多資訊。

先前，Gradle 使用根專案的名稱作為包含建置的建置名稱。現在，使用建置根目錄的名稱，如果根專案名稱不同，則不考慮根專案名稱。如果建置是透過設定檔包含的，則可以指定不同的建置名稱。

先前的行為有問題，因為它導致在建置期間的不同時間使用不同的名稱。

先前，Gradle 並未阻止將名稱 "buildSrc" 用於多專案建置的子專案或作為包含建置的名稱。現在，不允許這樣做。名稱 "buildSrc" 現在保留給建置額外建置邏輯的傳統 buildSrc 專案。

buildSrc 的典型使用不受此變更的影響。如果您在設定檔中指定 include("buildSrc") 或 includeBuild("buildSrc")，您才會受到影響。

Zinc 編譯器已升級至 1.3.0 版本。Gradle 不再支援為 Scala 2.9 建置。

Gradle 支援的最低 Zinc 編譯器版本為 1.2.0，而經過測試的最高版本為 1.3.0。

為了更輕鬆地選擇 Zinc 編譯器的版本，您現在可以配置 zincVersion 屬性

請移除您新增至 zinc 配置的任何明確相依性，並改用此屬性。如果您嘗試使用 com.typesafe.zinc:zinc 相依性，Gradle 將切換到新的 Zinc 實作。

過去，可以使用任何建置快取實作作為 local 快取。現在不再允許這樣做，因為本機快取必須始終是 DirectoryBuildCache。

使用 DirectoryBuildCache 以外的任何類型呼叫 BuildCacheConfiguration.local(Class) 將使建置失敗。使用 DirectoryBuildCache 類型呼叫這些方法將產生棄用警告。

請改用 getLocal() 和 local(Action)。

過去，當 Gradle 在封裝快取任務的結果時遇到問題時，Gradle 會忽略該問題並繼續執行建置。

當遇到損壞的快取成品時，Gradle 會移除已解壓縮的所有內容，並重新執行任務，以確保建置有機會成功。

雖然此行為旨在使建置成功，但這會產生隱藏問題的不利影響，並導致快取效能降低。

在 Gradle 6.0 中，封裝和解壓縮錯誤都會導致建置失敗，以便更輕鬆地發現這些問題。

先前，為了將建置快取用於 buildSrc 建置，您需要在 buildSrc 建置中複製您的建置快取配置。現在，它會自動使用頂層設定腳本定義的建置快取配置。

Gradle 模組中繼資料於 Gradle 5.3 正式推出，旨在解決多年來困擾相依性管理的許多問題，特別是在 Java 生態系統中，但不限於此。

在 Gradle 6.0 中，Gradle 模組中繼資料預設為啟用。

這表示，如果您使用 Gradle 發布程式庫並使用 maven-publish 或 ivy-publish 外掛程式，則 Gradle 模組中繼資料檔案始終會額外發布到傳統中繼資料。

傳統中繼資料檔案將包含一個標記，以便 Gradle 知道有其他中繼資料要使用。

發布 Gradle 模組中繼資料時，會驗證以下規則

這些也在規格中記錄。

如果 Gradle 無法在 repositories { } 區段中定義的儲存庫中找到模組的中繼資料檔案 (.pom 或 ivy.xml)，它現在會假設該模組不存在於該儲存庫中。

對於動態版本，相應模組的 maven-metadata.xml 需要存在於 Maven 儲存庫中。

先前，Gradle 也會尋找預設成品 (.jar)。當使用多個儲存庫時，此行為經常導致大量不必要的請求，從而減慢建置速度。

您可以透過新增 artifact() 中繼資料來源，選擇加入選定儲存庫的舊行為。

先前，如果 pom 封裝不是 jar、ejb、bundle 或 maven-plugin，則發布到 Maven 儲存庫的主要成品的副檔名會在發布期間變更為符合 pom 封裝。

此行為導致 Gradle 模組中繼資料損壞，並且由於處理不同的封裝類型而難以理解。

建置作者可以在建立成品時變更成品名稱以獲得與以前相同的結果 — 例如，透過明確設定 jar.archiveExtension.set(pomPackaging)。

對 ivy-publish 外掛程式進行了一些修正，以產生更正確的 ivy.xml 中繼資料。

因此，ivy.xml 檔案的內部結構已變更。runtime 配置現在包含更多資訊，這對應於 Java 程式庫的 runtimeElements 變體。default 配置應產生與以前相同的結果。

一般而言，建議使用者從 ivy.xml 遷移到新的 Gradle 模組中繼資料格式。

先前，buildSrc 專案在套用專案的設定腳本之前建置，並且其類別在腳本中可見。現在，buildSrc 在設定腳本之後建置，並且其類別對設定腳本不可見。buildSrc 類別對專案建置腳本和腳本外掛程式仍然可見。

可以透過宣告外部相依性，從設定腳本使用自訂邏輯。

先前，設定腳本內的任何 pluginManagement {} 區塊都在腳本的正常執行期間執行。

現在，它們以類似於 buildscript {} 或 plugins {} 的方式更早執行。這表示此類區塊內的程式碼無法參考腳本中其他位置宣告的任何內容。

進行此變更是為了在解析設定腳本本身的外掛程式時，也可以套用 pluginManagement 配置。

先前，透過使用 buildscript {} 新增至設定腳本的任何類別在腳本外部不可見。現在，它們對所有專案建置腳本都可見。

它們也對 buildSrc 建置腳本及其設定腳本可見。

進行此變更是為了使套用至設定腳本的外掛程式可以為整個建置貢獻邏輯。

就像使用 kotlin-dsl 外掛程式一樣，如果您套用 embedded-kotlin 外掛程式，現在也必須宣告可以找到 Kotlin 相依性的儲存庫。

對於早於 1.3.50 的 Kotlin IntelliJ 外掛程式版本，當Gradle JVM 設定為與專案 SDK 中的版本不同的版本時，Kotlin DSL 腳本會被錯誤地突顯顯示。只需將您的 IDE 外掛程式升級到 >= 1.3.50 的版本，即可還原正確的 Kotlin DSL 腳本突顯顯示行為。

在之前的版本中，Kotlin DSL 腳本被編譯為類別，這些類別實作了三個核心 Gradle 配置介面之一，以便隱式地將其 API 暴露給腳本。org.gradle.api.Project 用於專案腳本，org.gradle.api.initialization.Settings 用於設定腳本，org.gradle.api.invocation.Gradle 用於初始化腳本。

讓腳本實例實作它應該配置的模型物件的核心 Gradle 介面很方便，因為它使模型物件 API 立即對腳本主體可用，但這也是一個謊言，可能會在腳本本身用來代替模型物件時引起各種麻煩，專案腳本不是一個適當的 Project 實例，僅僅是因為它實作了核心 Project 介面，設定和初始化腳本也是如此。

在 6.0 中，所有 Kotlin DSL 腳本都編譯為實作新引入的 org.gradle.kotlin.dsl.KotlinScript 介面的類別，並且相應的模型物件現在作為腳本主體中的隱式接收器可用。換句話說，專案腳本的行為就像腳本主體包含在 with(project) { …​ } 區塊中一樣，設定腳本的行為就像腳本主體包含在 with(settings) { …​ } 區塊中一樣，而初始化腳本的行為就像腳本主體包含在 with(gradle) { …​ } 區塊中一樣。這表示相應的模型物件也作為腳本主體中的屬性可用，專案腳本的 project 屬性，設定腳本的 settings 屬性和初始化腳本的 gradle 屬性。

作為變更的一部分，設定腳本不再實作 SettingsScriptApi 介面，初始化腳本不再實作 InitScriptApi 介面。它們應替換為相應的模型物件介面，Settings 和 Gradle。

產生文件中時間戳記的實際用途非常有限，但是它們使得無法進行可重複的文件建置。因此，Javadoc 和 Groovydoc 任務現在配置為預設不再包含時間戳記。

Gradle 在執行 Checkstyle 時始終使用 configDirectory 作為 'config_loc' 的值。

在 Gradle 6.0 中，我們引入了一個新的進度事件 (org.gradle.tooling.events.test.TestOutputEvent) 來公開測試執行的輸出。這個新的事件打破了使用 StartEvent-FinishEvent 對來表達進度的慣例。TaskOutputEvent 是一個簡單的 ProgressEvent。

任務容器上的以下已棄用方法現在會導致錯誤

此外，以下已棄用的功能現在會導致錯誤

請使用 ObjectFactory.fileProperty()，取代以下現已移除的方法

請使用 ObjectFactory.directoryProperty()，取代以下現已移除的方法

org.gradle.api.Nullable 註解類型已被移除。請改用 JSR-305 的 javax.annotation.Nullable。

已棄用的 FindBugs 外掛程式已被移除。作為替代方案，您可以使用 SpotBugs 外掛程式，此外掛程式可在 Gradle 外掛程式入口網站取得。

已棄用的 JDepend 外掛程式已被移除。在 Gradle 外掛程式入口網站上，有許多社群提供的外掛程式可用於程式碼和架構分析。

已棄用的 OSGI 外掛程式已被移除。在 Gradle 外掛程式入口網站上，有許多社群提供的 OSGI 外掛程式可用。

已棄用的 announce 和 build-announcements 外掛程式已被移除。在 Gradle 外掛程式入口網站上，有許多社群提供的外掛程式可用於發送通知。

已棄用的 Compare Gradle Builds 外掛程式已被移除。請使用 build scans 進行建置分析和比較。

已棄用的 Play 外掛程式已被移除。外部替代方案，Play Framework 外掛程式，可從外掛程式入口網站取得。

抽象方法 compile() 不再由 AbstractCompile 宣告。

擴充 AbstractCompile 的工作可以實作它們自己的 @TaskAction 方法，並使用它們選擇的名稱。

它們也可以自由新增使用 @TaskAction 註解的方法，並使用 InputChanges 參數，而無需實作一個無參數的方法。

當工作屬性的類型為 ConfigurableFileCollection 時，則一旦工作開始執行，屬性參照的檔案集合將會忽略對集合內容所做的變更。這有兩個好處。首先，這可以防止在工作執行期間意外變更屬性值，這可能會導致 Gradle 最新檢查和建置快取查閱使用與工作動作所用不同的值。其次，這可以改善效能，因為 Gradle 可以計算值一次並快取結果。

這將在 Gradle 6.0 中變成錯誤。

直接建立 SignOperation 執行個體現在已棄用。相反地，應該使用 SigningExtension 的方法來建立這些執行個體。

這將在 Gradle 6.0 中變成錯誤。

宣告增量工作而不宣告輸出現在已棄用。請宣告檔案輸出或改用 TaskOutputs.upToDateWhen()。

這將在 Gradle 6.0 中變成錯誤。

WorkerExecutor.submit() 方法現在已棄用。現在應該使用新的 noIsolation()、classLoaderIsolation() 和 processIsolation() 方法來提交工作。如需使用這些方法的更多資訊，請參閱 Worker API 章節。

WorkerExecutor.submit() 將在 Gradle 8.0 中移除。

先前，工作相依性會針對類型為 Property<T> 的工作 @Input 屬性遭到忽略。這些相依性現在已適用，因此可以將工作輸出屬性附加到工作 @Input 屬性。

這可能會在工作相依性圖表中引入非預期的循環，其中輸出屬性的值會對應以產生輸入屬性的值。

先前，可以將不代表工作輸出的 Provider<File>、Provider<RegularFile> 或 Provider<Directory> 執行個體傳遞至 Task.dependsOn()。這些提供者會遭到靜默忽略。

這現在會造成錯誤，因為 Gradle 不知道如何建置不是工作輸出的檔案。

注意，仍然可以將傳回檔案且代表工作輸出的 Provider 傳遞至 Task.dependsOn()，例如 myTask.dependsOn(jar.archiveFile) 或 myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })，當 Provider 是工作的註解 @OutputFile 或 @OutputDirectory 屬性時。

先前，呼叫 Property.set(null) 始終會將屬性的值重設為「未定義」。現在，將使用與使用 convention() 方法的屬性相關聯的慣例來判斷屬性的值。

儲存庫和發佈名稱用於建構發佈的工作名稱。可能會提供導致工作名稱無效的名稱。發佈和儲存庫的名稱現在限制為 [A-Za-z0-9_\\-.]+。

Gradle 現在可防止內部相依性（例如 Guava）洩漏到 Worker API 動作使用的類別路徑中。這修正了 一個問題，其中 worker 需要使用 Gradle 內部也使用的相依性。

在先前的版本中，可能會依賴這些洩漏的類別。依賴此行為的外掛程式現在將會失敗。若要修正此外掛程式，worker 應在其類別路徑中明確包含所有必要的相依性。

PMD 外掛程式已升級為預設使用 PMD 6.15.0 版，而非 6.8.0 版。

由 wreulicke 貢獻

先前，組態的所有副本始終具有名稱 <OriginConfigurationName>Copy。現在，當建立多個副本時，每個副本都將具有唯一名稱，方法是從第二個副本開始新增索引。（例如 CompileOnlyCopy2）

Gradle 5.6 不再在 Eclipse 模型中提供自訂類別路徑屬性。相反地，它為 Eclipse 測試原始碼提供屬性。此變更需要 Buildship 3.1.1 版或更新版本。

現在使用 Kotlin 1.3.41 編譯使用 kotlin-dsl 外掛程式編寫的 Gradle Kotlin DSL 腳本和 Gradle 外掛程式。

請參閱 Kotlin 部落格文章和 變更日誌，以取得有關包含變更的更多資訊。

現在支援的最低 Kotlin Gradle 外掛程式版本為 1.2.31。先前為 1.2.21。

在功能衝突的情況下，先前版本的 Gradle 會自動選擇具有最高功能版本的模組。從 5.6 開始，這是一種可選擇加入的行為，可以使用以下方式啟用

如需更多選項，請參閱文件中的功能章節。

當 Gradle 必須出於各種原因移除工作的輸出檔案時，它將不會遵循符號連結目錄。符號連結本身將會被刪除，但連結目錄的內容將保持不變。

內建的 Play 外掛程式已被棄用，將由新的 Play Framework 外掛程式取代，此外掛程式可從外掛程式入口網站取得。

建置比較外掛程式已被棄用，並將在下一個 Gradle 主要版本中移除。

Build scans 可深入了解您的建置，您可以使用 Develocity 直接比較兩個建置的 build-scans。

透過 EclipseProject.setName(…​) 配置的專案名稱在所有情況下都受到 Gradle 和 Buildship 的尊重，即使名稱導致衝突和匯入/同步錯誤也是如此。

如果專案名稱與 Eclipse 工作區中的其他專案名稱衝突，Gradle 現在可以對這些名稱進行重複資料刪除。這可能會導致具有使用者指定名稱的專案具有不同的 Eclipse 專案名稱。

需要即將推出的 Buildship 3.1.1 版本才能利用此行為。

由 Christian Fränkel 貢獻

JaCoCo 外掛程式已升級為預設使用 JaCoCo 0.8.4 版，而非 0.8.3 版。

由 Evgeny Mandrikov 貢獻

與 Gradle 一起發佈的 Ant 版本已從 1.9.13 升級至 1.9.14。

這會影響 Kotlin DSL 建置腳本，這些腳本會使用 ExtensionAware 擴充成員，例如 dependencies {} 區塊內的 extra 屬性存取器。這些成員的接收器將不再是封閉的 Project 執行個體，而是 dependencies 物件本身，最內層符合 ExtensionAware 的接收器。為了在 dependencies {} 內定址 Project 額外屬性，必須明確限定接收器，即 project.extra 而不是僅僅 extra。受影響的擴充功能也包括 the<T>() 和 configure<T>(T.() → Unit)。

先前版本的 Gradle 在某些複雜的相依性圖表中，在存在大量排除項時，可能會產生錯誤的結果或隨機的相依性順序。為了減輕此問題，已重寫計算排除項的演算法。在某些罕見的情況下，由於正確性變更，這可能會導致解析結果出現一些差異。

當使用 PROCESS 隔離時，由 Worker API 啟動的 worker 守護程序的系統類別路徑已縮減為最少的 Gradle 基礎架構集。使用者程式碼仍然隔離到單獨的類別載入器中，以將其與 Gradle 執行時期隔離。對於使用 worker API 的工作來說，這應該是一個透明的變更，但先前版本的 Gradle 將使用者程式碼和 Gradle 內部程式碼混合在 worker 程序中。依賴諸如 java.class.path 系統屬性之類事物的 Worker 動作可能會受到影響，因為 java.class.path 現在僅代表 Gradle 內部程式碼的類別路徑。

現在已棄用針對本機建置快取使用自訂建置快取實作。未來唯一允許的類型將是 DirectoryBuildCache。支援將自訂建置快取實作作為遠端建置快取使用方面沒有任何變更。

可透過 JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL 存取的 Google Hosted Libraries URL 已變更為使用 HTTPS 協定。此變更也影響透過 googleApis() 配置的 Ivy 儲存庫。

從 Gradle 5.0 到 5.2.1（包含）存在一個錯誤，其中強制平台可能會包含相依性而不是約束。每當 POM 檔案同時定義相依性和「約束」（透過 <dependencyManagement>）且您使用 enforcedPlatform 時，就會發生這種情況。Gradle 5.3 修正了此錯誤，這表示如果您依賴此損壞的行為，則解析結果可能會有所不同。同樣地，Gradle 5.3 將不再嘗試下載 platform 和 enforcedPlatform 相依性的 jar 檔案（因為它們應該只引入約束）。

如果您套用任何 Java 外掛程式，Gradle 現在將盡力選擇與正在編譯的模組的目標相容性相符的相依性。實際上，這表示如果您有針對 Java 8 建置的模組 A 和針對 Java 8 建置的模組 B，則不會有任何變更。但是，如果 B 是針對 Java 9+ 建置的，則它不再是二進位相容的，Gradle 會抱怨並顯示如下錯誤訊息

一般而言，這表示您的專案配置錯誤，並且您的相依性不相容。但是，在某些情況下，您可能仍然想要這樣做，例如當您的模組中只有子集的類別實際上需要 Java 9 相依性，並且不打算在較早的版本上使用時。Java 通常不鼓勵您這樣做（您應該改為分割您的模組），但如果您遇到此問題，您可以透過在消費者端停用此新行為來解決此問題

如果您有一個 Maven 相依性指向 Ivy 相依性，其中 default 組態相依性與 compile + runtime + master 組態相依性不符，而且該 Ivy 相依性已被取代（使用 resolutionStrategy.force、resolutionStrategy.eachDependency 或 resolutionStrategy.dependencySubstitution），則此修正程式將會影響您。Gradle 5.0 之前的舊版行為仍然存在，而不是被改進的 pom 支援引入的變更所取代。

對於 clean 工作、所有 Delete 工作和 project.delete {} 作業，當存在接合點和符號連結時，Gradle 不再忽略 Windows 上的 followSymlink 選項。

在先前的 Gradle 版本中，除非也在發佈組態中新增了專案層級註冊的其他成品，否則 maven-publish 或 ivy-publish 不會發佈這些成品。

使用 Gradle 5.3，現在已正確考量並發佈這些成品。

這表示在專案和發佈、Ivy 或 Maven 上註冊的成品將會導致發佈失敗，因為它會建立重複的項目。修正方法是從發佈組態中移除這些成品。

Sign 工作的輸入和輸出檔案現在分別透過 Signature.getToSign() 和 Signature.getFile() 追蹤。

在 Gradle 5.0 中，使用 ObjectFactory 建立的集合屬性執行個體將不會定義任何值，這需要外掛程式作者明確設定初始值。這被證明是笨拙且容易出錯的，因此 ObjectFactory 現在傳回以空集合作為其初始值的執行個體。

由於 JDK 11 不再支援變更執行中程序的工作目錄，因此現在禁止透過 worker 的 fork 選項設定 worker 的工作目錄。所有 worker 現在都使用相同的工作目錄以啟用重複使用。請改為將檔案和目錄作為引數傳遞。請參閱 Worker API 文件中的範例。

為了擴展我們的慣用語 Provider API 實務，org.gradle.nativeplatform.tasks.LinkSharedLibrary 中的安裝名稱屬性受到此變更的影響。

為了擴展我們的慣用語 Provider API 實務，WindowsResourceCompile 工作已轉換為使用 Provider API。

傳遞額外的編譯器引數現在遵循與 CppCompile 和其他工作相同的模式。

beforeResolve 動作清單不再在複製的組態和原始組態之間共用。相反地，複製的組態會在建立副本時接收 beforeResolve 動作的副本。在複製後（新增至任一組態）新增的任何 beforeResolve 動作都不會在原始組態和副本之間共用。這可能會中斷依賴先前行為的外掛程式。

原生元件上的孵化中 operatingSystems 屬性已由 targetMachines 屬性取代。