將您的建置從 Gradle 6.x 升級到 7.0

IdeaContentRoot 介面中已移除 getGeneratedSourceDirectories() 和 getGeneratedTestDirectories() 方法。用戶端應將這些調用替換為 getSourceDirectories() 和 getTestDirectories()，並在傳回的實例上使用 isGenerated() 方法。

由於更新到下一個主要版本的 Groovy，您在升級到 Gradle 7.0 時可能會遇到一些小問題。

新版本的 Groovy 具有更嚴格的解析器，無法編譯可能在先前 Groovy 版本中接受的程式碼。如果您遇到語法錯誤，請檢查Groovy 問題追蹤器和Groovy 3 發行重點。

一些非常特定的迴歸已在下一個 Groovy 次要版本中修復。

自 Gradle 成立以來，它提供了 compile 和 runtime 配置來宣告相依性。然而，這些配置不支援細緻的相依性範圍。因此，Gradle 3.4 中引入了更好的替代方案

在 Gradle 7 中，compile 和 runtime 配置都已移除。因此，您必須移轉到上述的 implementation 和 api 配置。如果您仍然為 Java 程式庫使用 java 外掛程式，則需要改為應用 java-library 外掛程式。

您可以透過閱讀Java 程式庫外掛程式文件，找到有關新配置的優點以及使用哪個配置來取代 compile 和 runtime 的更多詳細資訊。

ProjectBuilder API 用於在單元測試中檢查 Gradle 建置。此 API 過去會在系統臨時目錄下建立臨時專案檔案，如 java.io.tmpdir 所定義。

API 現在會在 Test 任務的臨時目錄下建立臨時專案檔案。此路徑通常位於專案建置目錄下。當測試預期特定的檔案路徑時，這可能會導致測試失敗。

如果測試使用 ProjectBuilder.withProjectDir(…​)，則不受影響。

使用TestKit API 的測試過去會在系統臨時目錄下建立臨時檔案，如 java.io.tmpdir 所定義。這些檔案用於儲存 Gradle 發行版的副本或另一個僅用於測試的 Gradle 使用者首頁。

TestKit 測試現在會在 Test 任務的臨時目錄下建立臨時檔案。此路徑通常位於專案建置目錄下。當測試預期特定的檔案路徑時，這可能會導致測試失敗。

如果測試使用 GradleRunner.withTestKitDir(…​)，則不受影響。

Windows 上的檔案系統監看實作會將鎖定新增至根專案目錄，以便監看變更。當您嘗試在使用 TestKit 執行建置後刪除根專案目錄時，這可能會導致錯誤。例如，將 TestKit 與 JUnit 的 @TempDir 擴展或 TemporaryFolder 規則一起使用的測試可能會遇到此問題。為了避免這些檔案鎖定的問題，TestKit 會針對透過 GradleRunner 在 Windows 上執行的建置停用檔案系統監看。如果您想要覆寫預設行為，您可以透過將 --watch-fs 傳遞至 GradleRunner.withArguments() 來啟用檔案系統監看。

maven 外掛程式已移除。您應該改用 maven-publish 外掛程式。

請參閱Maven Publish 外掛程式的文件以取得更多詳細資訊。

uploadArchives 任務與舊版 Ivy 或 Maven 發佈機制結合使用。它已在 Gradle 7 中移除。您應該移轉到 maven-publish 或 ivy-publish 外掛程式來替代。

請參閱Maven Publish 外掛程式的文件，以了解如何在 Maven 儲存庫上發佈。請參閱Ivy Publish 外掛程式的文件，以了解如何在 Ivy 儲存庫上發佈。

在相依性版本排序的上下文中，-SNAPSHOT 版本現在被認為在最終版本之前，但在任何 -RC 版本之後。也考慮了更多特殊的版本字尾。這使 Gradle 演算法更接近 Maven 演算法，以用於眾所周知的版本字尾。

查看文件，了解 Gradle 應用的所有規則。

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

以下用於實驗性 JavaScript 整合的外掛程式現在已從發行版中移除：coffeescript-base、envjs、javascript-base、jshint、rhino。

如果您使用了這些外掛程式，儘管它們具有實驗性，您可能會在外掛程式入口網站中找到合適的替代方案。

採用配置區塊的 layout 方法已移除，並替換為patternLayout。

Gradle 建置由其在目前或父目錄中找到的 settings.gradle(.kts) 檔案定義。如果沒有設定檔，則 Gradle 建置未定義，並且 Gradle 在嘗試執行任務時會產生錯誤。

若要修正此錯誤，請為建置建立 settings.gradle(.kts) 檔案。

此規則的例外情況是使用 init 任務或使用診斷命令列旗標（例如 --version）調用 Gradle。

Gradle 6.x 會警告使用者關於錯誤的行為，並在此情境中忽略目標動作。從 7.0 開始，相同的情況會產生錯誤。應調整外掛程式和建置腳本，以僅在配置時調用 afterEvaluate。如果您有此類建置失敗，並且相關的 afterEvaluate 陳述式在您的建置原始碼中宣告，則您可以直接刪除它。如果 afterEvaluate 在外掛程式中宣告，則向外掛程式維護者回報問題。

請改用 ObjectFactory#fileCollection()。

請改用 libsDirectory 和 distsDirectory 屬性。

現有的用法應替換為 RuntimeException。

getBaseName() 和 setBaseName() 方法已從 Distribution 類別中移除。用戶端應將用法替換為 distributionBaseName 屬性。

使用 AbstractTask 類型或擴展 AbstractTask 的類型註冊任務已在 Gradle 6.5 中棄用，現在在 Gradle 7.0 中是一個錯誤。您可以改用 DefaultTask。

BuildListener.buildStarted(Gradle) 已在 Gradle 6.0 中棄用，現在在 Gradle 7.0 中已移除。請改用 BuildListener.beforeSettings(Settings)。

自 Gradle 5.0 以來，以下 API 已無法透過命令列選項使用，現在已移除：StartParameter.useEmptySettings()、StartParameter.isUseEmptySettings()、StartParameter.setSearchUpwards(boolean) 和 StartParameter.isSearchUpwards()。

Gradle 不再支援在同層目錄中名為 master 的目錄中探索設定檔。如果您的建置仍然使用此已棄用的功能，請考慮重構建置，使根目錄與專案階層的實體根目錄相符。您可以在使用者手冊中找到有關如何建構 Gradle 建置的更多資訊。或者，您仍然可以透過僅從 master 目錄調用建置，並使用任務的完整限定路徑，在此類建置中執行任務。

編譯、測試和執行現在對於任何定義模組的原始碼集（透過包含 module-info.java 檔案）自動運作。通常，這是您需要的行為。如果這在您手動配置模組路徑或使用第三方外掛程式的情況下導致問題，您仍然可以透過在 java 擴展或個別任務上將 modularity.inferModulePath 設定為 false 來選擇退出。

ValidateTaskProperties 任務已移除，並由 ValidatePlugins 任務取代。

ImmutableFileCollection 類型已移除。請改用工廠方法。可以透過 Project.layout 取得專案版面配置的句柄。

方法 ComponentSelectionReason.getDescription 已移除。它已由 ComponentSelectionReason.getDescriptions 取代，後者傳回 ComponentSelectionDescriptor 的列表，每個列表都有 getDescription。

以下已棄用的建構子已移除

本機建置快取配置現在需要透過 BuildCacheConfiguration.local() 完成。

此內部 API 用於外掛程式，其中包括 Nebula 外掛程式，並且已在 Gradle 5.x 時間軸中棄用，現在已移除。最新的外掛程式版本不應再參考它。

checkstyle 外掛程式現在對於以下配置失敗

建置應使用 checkstyle 區塊宣告 checkstyle 配置

Gradle 6.x 會警告使用者關於錯誤的行為，然後傳回可能不正確的提供者值。從 7.0 開始，相同的情況會產生錯誤。應調整外掛程式和建置腳本，以在任務完成後查詢提供者的映射值，例如任務輸出屬性。

Gradle 6.0 開始警告有關任務定義的問題（例如不正確定義的輸入或輸出）。對於 Gradle 7.0，這些警告現在是錯誤，並且會使建置失敗。

先前的 Gradle 版本在特定配置中的衝突解決行為不一致：- 您的專案宣告對已發布模組的嚴格依賴（例如，com.mycompany:some-module:1.2!!，其中 1.2!! 是對 1.2 嚴格依賴的簡寫表示法）- 您的建置實際上提供了更高版本的 com.mycompany:some-module

先前的 Gradle 版本會成功，即使存在嚴格約束，仍選擇專案依賴。從 Gradle 7 開始，這將觸發依賴解析失敗。

請參閱 此 issue 以取得更多背景資訊。

讓一個任務在某個位置產生輸出，而另一個任務將該位置作為輸入來使用，但消費者任務不依賴生產者任務的做法已被棄用。解決此問題的方法是從消費者新增對生產者的依賴。

當複製操作（或任何使用 org.gradle.api.file.CopySpec 的操作）遇到重複項目，且未設定重複策略時，Gradle 7 現在會失敗。請查看 CopySpec 文件 以取得詳細資訊。

org.gradle.jvm.toolchain 中支援 Java Toolchain 功能的 API 現在標記為 @NonNull。

這可能會影響 Kotlin 消費者，因為 API 的回傳型別不再可為 null。

先前，Eclipse 匯入的專案僅包含主要和測試來源集的依賴項。自訂來源集的編譯和執行時期類別路徑被忽略。

自 Gradle 6.8 起，匯入到 Eclipse 的專案包含建置所定義的每個來源集的編譯和執行時期類別路徑。

先前，在 SourceTask 中宣告的來源的最新檢查和建置快取金鑰計算期間，會將空目錄納入考量。這表示包含空目錄的來源樹，以及另一個不包含空目錄的相同來源樹，將被視為不同的來源，即使任務會產生相同的輸出。在 Gradle 6.8 中，SourceTask 現在在執行最新檢查和建置快取金鑰計算時會忽略空目錄。在絕大多數情況下，這是所需的行為，但任務可能會擴充 SourceTask，但在來源中存在空目錄時，也會產生不同的輸出。對於關注此問題的任務，您可以公開一個不帶 @IgnoreEmptyDirectories 註解的單獨屬性，以便捕捉這些變更

發布具有強制平台依賴的元件現在會觸發驗證錯誤，防止意外發布錯誤的中繼資料：強制平台的使用案例應僅限於應用程式，而不是可以從另一個程式庫或應用程式取用的事物。

如果由於某些原因，您仍然想要發布具有強制平台依賴的元件，您可以按照文件停用驗證。

為了方便起見，Gradle 的檔案樹套用了一些預設排除模式 — 事實上與 Ant 的預設值相同。請參閱使用者手冊以取得更多資訊。有時，Ant 的預設排除項會帶來問題，例如當您想要在封存檔中包含 .gitignore 時。

在執行階段變更 Gradle 的預設排除項可能會導致最新檢查的正確性問題。因此，您只能在設定腳本中變更 Gradle 的預設排除項，請參閱使用者手冊中的範例。

在 mustRunAfter、shouldRunAfter 和 finalizedBy 任務方法中直接參照來自包含建置的任務已被棄用。使用 mustRunAfter 和 shouldRunAfter 的任務排序以及由 finalizedBy 指定的終結器應在建置內用於任務排序。如果您碰巧使用上述方法定義了跨建置任務排序，請考慮重新建構此類建置並將它們彼此分離。

當您的建置依賴於在同層目錄中名為 master 的目錄中尋找設定檔時，Gradle 將發出棄用警告。

如果您的建置使用此功能，請考慮重構建置，使根目錄與專案階層的實體根目錄相符。

或者，您仍然可以透過僅從 master 目錄調用建置，並使用任務的完整路徑來執行此類建置中的任務。

Gradle Kotlin DSL 擴充功能已變更為偏好 Gradle 的 Action<T> 型別，而不是 Kotlin 函數型別。

雖然此變更對於 Kotlin 用戶端應是透明的，但呼叫 Kotlin DSL 擴充功能的 Java 用戶端需要更新為使用 Action<T> API。

先前，buildSrc 的建置方式使其從根建置中忽略包含的建置。

自 Gradle 6.7 起，buildSrc 可以看到來自根建置的任何包含的建置。這可能會導致依賴項從 buildSrc 中包含的建置中被取代。如果 buildSrc 需要包含的建置，這也可能會變更某些建置的執行順序。

為了方便起見，Gradle 的檔案樹套用了一些預設排除模式 — 事實上與 Ant 的預設值相同。請參閱使用者手冊以取得更多資訊。有時，Ant 的預設排除項會帶來問題，例如當您想要在封存檔中包含 .gitignore 時。

在執行階段變更 Gradle 的預設排除項可能會導致最新檢查的正確性問題，並且已被棄用。您只能在設定腳本中變更 Gradle 的預設排除項，請參閱使用者手冊中的範例。

Gradle 允許將 Configuration 的實例直接用作依賴項

此行為現在已被棄用，因為它令人困惑：人們可能會期望先解析「依賴配置」，然後將解析結果作為依賴項新增到包含配置中，但事實並非如此。棄用版本可以替換為實際行為，即配置繼承

在新增對表達變體支援在依賴項替換中的支援時，一個錯誤修復引入了一個行為變更，某些建置可能依賴於此變更。先前，被替換的依賴項仍會使用原始選擇器的屬性，而不是來自替換選擇器的屬性。

透過該變更，圍繞具有更豐富選擇器（例如平台依賴項）的依賴項的現有替換將不再像以前那樣工作。在目標選擇器中定義變體感知部分已成為強制性的。

如果您有以下情況，可能會受到此變更的影響

如果您受到影響，請參閱文件以解決問題。

AbstractTask 是一個內部類別，在公共 API 上可見，作為公共型別 DefaultTask 的父類別。AbstractTask 將在 Gradle 7.0 中移除，以下在 Gradle 6.5 中已棄用

Gradle 6.4 預設啟用增量分析。增量分析僅在 PMD 6.0.0 或更高版本中可用。如果您想要使用舊版本的 PMD，您需要停用增量分析

在 Gradle 6.4 中，用於依賴項鎖定 LockMode的孵化 API 已變更。該值現在透過 Property<LockMode> 而不是直接 setter 來設定。這表示 Kotlin DSL 的值設定表示法必須更新

Groovy DSL 的使用者不應受到影響，因為表示法 lockMode = LockMode.STRICT 仍然有效。

如果 Java 程式庫是使用 Gradle Module Metadata 發布的，則其支援的 Java 版本資訊會編碼在 org.gradle.jvm.version 屬性中。預設情況下，此屬性設定為您在 java.targetCompatibility 中設定的內容。如果未設定，則會設定為執行 Gradle 的目前 Java 版本。變更特定編譯任務的版本，例如 javaCompile.targetCompatibility 對該屬性沒有影響，如果未手動調整該屬性，則會導致錯誤的資訊。現在已修正此問題，並且屬性預設為與從中建置已發布 jar 的來源關聯的編譯任務的設定。

從 6.0 到 6.3.x 的 Gradle 版本在 Ivy 儲存庫上發布時可能會產生錯誤的 Gradle Module Metadata，該儲存庫具有自訂儲存庫版面配置。從 6.4 開始，如果 Gradle 偵測到您正在使用自訂儲存庫版面配置，將不再發布 Gradle Module Metadata。

此版本在不同位置引入了一些新屬性 — mainClass、mainModule、modularity —。由於這些是非常通用的名稱，因此您很有可能在建置腳本中將其中一個用作變數名稱。然後，新屬性可能會以不想要的方式遮蔽您的其中一個變數，從而導致在存取屬性而不是同名的區域變數時發生建置失敗。您可以透過重新命名建置腳本中的相應變數來修正此問題。

受影響的是 application {} 和 java {} 配置區塊內、使用 project.javaexec {} 的 Java 執行設定內，以及各種任務配置（JavaExec、CreateStartScripts、JavaCompile、Test、Javadoc）內的配置程式碼。

Gradle 不再將註解處理器類別路徑作為提供的依賴項包含在 IDEA 中。IDEA 在編譯時看到的依賴項與 Gradle 在解析編譯類別路徑（名為 compileClasspath 的配置）後看到的相同。這可以防止註解處理器依賴項洩漏到專案的程式碼中。

在 Gradle 引入增量註解處理支援之前，IDEA 需要所有註解處理器都在編譯類別路徑上，以便在 IDEA 中編譯時能夠執行註解處理。這已不再必要，因為 Gradle 有一個單獨的註解處理器類別路徑。當匯入具有註解處理器的 Gradle 專案時，註解處理器的依賴項不會新增到 IDEA 模組的類別路徑中。

Gradle 6.3 不支援 32 位元 Unix 系統和舊版 FreeBSD（舊於 FreeBSD 10）的豐富主控台。Microsoft Windows 32 位元不受影響。

Gradle 將繼續在 32 位元系統上建置專案，但不再顯示豐富主控台。

幾乎每個 Gradle 專案都有 default 和 archives 配置，這些配置由 base 外掛程式新增。在現代 Gradle 建置中，使用變體感知依賴項管理和新發布外掛程式的建置中，不再使用這些配置。

雖然這些配置目前將保留在 Gradle 中以實現向後相容性，但現在棄用使用它們來宣告依賴項或解析依賴項。

解析這些配置從來不是預期的使用案例，並且僅在早期 Gradle 版本中才有可能，因為每個配置都是可解析的。對於宣告依賴項，請使用您使用的外掛程式提供的配置，例如Java Library 外掛程式提供的配置。

JVM 專案中的類別路徑現在明確請求 org.gradle.category=library 屬性。如果無法使用特定程式庫，這會導致更清晰的錯誤訊息。例如，當程式庫不支援所需的 Java 版本時。實際效果是，現在所有平台依賴項都必須宣告為此類依賴項。之前，平台依賴項也可以工作，只是偶然地，當省略本機平台或使用 Gradle Module Metadata 發布的平台的 platform() 關鍵字時。

Gradle 6.2 和 Gradle 6.2.1 中存在一個回歸，導致在專案根目錄 gradle.properties 檔案中設定的 Gradle 屬性洩漏到 buildSrc 建置和根目錄包含的任何建置中。

如果 buildSrc 建置或包含的建置突然發現來自專案根目錄 gradle.properties 檔案的屬性的意外或不相容的值，這可能會導致您的建置開始失敗。

此回歸已在 Gradle 6.2.2 中修正。

在任務完成之前查詢對應輸出屬性的值可能會導致奇怪的建置失敗，因為它表示可能會錯誤地使用過時或不存在的輸出。此行為已被棄用，將發出棄用警告。這將在 Gradle 7.0 中變成錯誤。

以下範例示範了此問題，其中在 Producer 執行之前解析了 Producer 的輸出檔案

如果在 producer 完成之前完成，則查詢 consumer.threadPoolSize 的值將產生棄用警告，因為輸出檔案尚未產生。

以下方法已停用，不應再使用。它們將在 Gradle 7.0 中移除。

Gradle 2.x 中引入了一組替代外掛程式，用於 Java 和 Scala 開發，作為基於「軟體模型」的實驗。這些外掛程式現在已棄用，最終將被移除。如果您仍在使用這些舊外掛程式之一（java-lang、scala-lang、jvm-component、jvm-resources、junit-test-suite），請查閱關於建置 Java & JVM 專案的文件，以確定哪些穩定的 JVM 外掛程式適合您的專案。

在 Gradle 6.0 中，ProjectLayout 服務透過服務注入提供給 worker actions。此服務允許可變狀態洩漏到 worker action 中，並引入了一種在 worker action 中未宣告依賴項的方式。

ProjectLayout 已從可用服務中移除。正在使用 ProjectLayout 的 worker actions 應切換為注入 projectDirectory 或 buildDirectory 作為參數。

從 Gradle 6.2 開始，Gradle 在上傳之前執行健全性檢查，以確保您不會上傳過時的檔案（由另一個建置產生的檔案）。這為使用 components.java 元件上傳的 Spring Boot 應用程式帶來了問題

這是因為 Spring Boot 應用程式停用了主要的 jar 任務，而元件期望它存在。因為 bootJar 任務預設使用與主要 jar 任務相同的文件，所以先前版本的 Gradle 會

一個解決方法是告訴 Gradle 要上傳什麼。如果您想要上傳 bootJar，則需要配置傳出配置來執行此操作

或者，您可能想要重新啟用 jar 任務，並使用不同的分類器新增 bootJar。