將您的組建從 Gradle 5.x 升級到 6.0

自 Gradle 3.4 起，已不建議在 Java 生態系統外掛中使用 compile 和 runtime 設定。

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

uploadArchives 任務和 maven 外掛已不建議使用。

使用者應透過使用 Gradle 發布系統 來遷移，方法是使用 maven-publish 或 ivy-publish 外掛。這些外掛自 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 外掛版本 3.4 及更新版本。

對於 Gradle 6，必須使用 Develocity 外掛取代 Build Scan 外掛。這也需要變更外掛的套用方式。請參閱 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。

對 BuildCacheConfiguration.local(Class) 的呼叫，如果類型不是 DirectoryBuildCache，建置會失敗。使用 DirectoryBuildCache 類型呼叫這些方法會產生不建議使用的警告。

改用 getLocal() 和 local(Action)。

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

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

雖然此行為的目的是讓建置成功，但它卻有隱藏問題的反效果，並導致快取效能降低。

在 Gradle 6.0 中，封裝和解封裝錯誤都會導致建置失敗，因此這些問題會更容易浮現。

以前，若要對 buildSrc 建置使用建置快取，您需要在 buildSrc 建置中複製您的建置快取組態。現在，它會自動使用頂層設定指令碼定義的建置快取組態。

Gradle 模組元資料在 Gradle 5.3 中正式推出，Gradle 模組元資料 建立來解決多年來困擾相依性管理的許多問題，特別是，但並非僅限於 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 外掛程式。請使用 建置掃描 進行建置分析和比較。

已移除已棄用的 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 屬性。

這可能會在任務依賴關係圖中引發意外的循環，其中輸出屬性的值會被對應到，以產生輸入屬性的值。

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

這現在會出錯，因為 Gradle 不知道如何建置不是任務輸出的檔案。

請注意，仍然可以傳遞 Task.dependsOn() 一個傳回檔案且代表任務輸出的 Provider，例如 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 動作所使用的類別路徑中。這修正了 一個問題，其中工作需要使用 Gradle 內部也使用的依賴關係。

在之前的版本中，可以依賴這些洩漏的類別。依賴此行為的插件現在將會失敗。若要修復插件，工作人員應在其類別路徑中明確包含所有必要的相依性。

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

由 wreulicke 提供

先前，組態的所有複本名稱皆為 <OriginConfigurationName>Copy。現在在建立多個複本時，每個複本將具有唯一名稱，從第二個複本開始加上索引。（例如，CompileOnlyCopy2）

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

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

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

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

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

請參閱 文件的功能區段，以取得更多選項。

當 Gradle 必須移除任務的輸出檔案時，它不會追蹤符號連結目錄。符號連結本身將會刪除，但連結目錄的內容將保持完整。

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

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

建置掃描 會顯示更深入的建置見解，您可以使用 Develocity 直接比較兩個建置的建置掃描。

透過 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。

這會影響使用 ExtensionAware 擴充成員的 Kotlin DSL 建置指令碼，例如 dependencies {} 區塊內的 extra 屬性存取器。這些成員的接收器不再是封裝的 Project 執行個體，而是 dependencies 物件本身，也就是最內層的 ExtensionAware 相符接收器。若要解決 dependencies {} 內的 Project 額外屬性，接收器必須明確限定，也就是 project.extra，而不能只有 extra。受影響的擴充功能還包括 the<T>() 和 configure<T>(T.() → Unit)。

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

使用 PROCESS 隔離時，工作人員 API 啟動的工作程序精靈的系統類別路徑已減少到 Gradle 基礎架構的最小組。使用者程式碼仍會隔離到一個獨立的類別載入器中，以將其與 Gradle 執行時期隔離。這應該是使用工作人員 API 的任務的透明變更，但舊版本的 Gradle 會在工作程序中混合使用者程式碼和 Gradle 內部元件。依賴於 java.class.path 系統屬性等事項的工作人員動作可能會受到影響，因為 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 通常不鼓勵您這樣做（您應該拆分您的模組），但如果您遇到這個問題，您可以透過在消費者端停用這個新行為來解決

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

在存在連接點和符號連結的情況下，Gradle 不再忽略 Windows 上 clean 任務、所有 Delete 任務和 project.delete {} 操作的 followSymlink 選項。

在以前的 Gradle 版本中，在專案層級註冊的額外人工製品不會由 maven-publish 或 ivy-publish 發布，除非它們也新增為發布組態中的人工製品。

使用 Gradle 5.3，這些人工製品現在會正確計算並發布。

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

Sign 任務的輸入和輸出檔案現在會透過 Signature.getToSign() 和 Signature.getFile() 來追蹤。

在 Gradle 5.0 中，使用 ObjectFactory 建立的集合屬性實例不會定義值，需要外掛作者明確設定初始值。這被證明很麻煩且容易出錯，因此 ObjectFactory 現在會傳回初始值為空集合的實例。

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

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

為了擴充我們的慣用語法 Provider API 實務，WindowsResourceCompile 任務已轉換為使用 Provider API。

傳遞額外的編譯器引數現在遵循與 CppCompile 及其他任務相同的模式。

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

原生元件上的正在孵化的 operatingSystems 屬性已變更為 targetMachines 屬性。