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

getGeneratedSourceDirectories() 和 getGeneratedTestDirectories() 方法已從 IdeaContentRoot 介面移除。客戶端應將這些呼叫替換為 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 任務呼叫 Gradle，或使用診斷命令列旗標，例如 --version。

Gradle 6.x 會警告使用者錯誤的行為，並在這種情況下忽略目標動作。從 7.0 開始，相同的情況會產生錯誤。外掛程式和建置指令碼應調整為僅在設定時間呼叫 afterEvaluate。如果您有這種建置失敗，且相關的 afterEvaluate 陳述宣告在您的建置來源中，則您可以直接刪除它。如果 afterEvaluate 宣告在外掛程式中，則向外掛程式維護人員回報問題。

請改用 ObjectFactory#fileCollection()。

請改用 libsDirectory 和 distsDirectory 屬性。

現有用法應改用 RuntimeException。

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

在 Gradle 6.5 中已棄用使用 AbstractTask 類型或使用延伸 AbstractTask 的類型來註冊任務，且現在在 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 開始，這會觸發依賴關係解決失敗。

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

如果任務在某個位置產生輸出，而另一個任務透過將該位置作為輸入來使用該輸出，但使用者任務未依賴於產生者任務，則此情況已被棄用。解決此問題的方法是 從使用者新增對產生者的依賴關係。

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

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

這可能會影響 Kotlin 使用者，因為 API 的傳回類型不再為可為空。

先前，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> 設定值，而不是直接設定器。這表示必須更新 Kotlin DSL 中設定值的表示法

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

如果 Java 函式庫是使用 Gradle 模組元資料發布的，則它支援的 Java 版本資訊會編碼在 org.gradle.jvm.version 屬性中。預設情況下，此屬性會設定為您在 java.targetCompatibility 中設定的內容。如果未設定，則會設定為執行 Gradle 的目前 Java 版本。變更特定編譯工作的版本，例如 javaCompile.targetCompatibility，不會對該屬性造成影響，如果未手動調整屬性，則會導致錯誤的資訊。此問題現已修正，且屬性預設值會變更為與編譯工作設定相關聯，而編譯工作會從已建置已發布 jar 的來源中產生。

6.0 到 6.3.x 含括的 Gradle 版本在於自訂存放庫配置中發佈時，可能會產生錯誤的 Gradle 模組元資料。從 6.4 開始，如果 Gradle 偵測到您正在使用自訂存放庫配置，將不再發佈 Gradle 模組元資料。

此版本在不同的地方引入了幾個新的屬性，例如 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 專案都有 預設 和 檔案 組態，它們是由 基本 外掛新增的。這些組態不再用於使用 變異感知相依性管理 和 新發布外掛 的現代 Gradle 建置中。

雖然這些組態將暫時保留在 Gradle 中以維持向後相容性，但現在不建議使用它們來宣告相依性或解析相依性。

解析這些組態從來就不是預期的使用案例，而且只有在較早的 Gradle 版本中才有可能，因為在這些版本中 每個 組態都是可解析的。若要宣告相依性，請使用您所使用的外掛所提供的組態，例如 Java 函式庫外掛。

JVM 專案中的類別路徑現在明確要求 org.gradle.category=library 屬性。如果無法使用特定函式庫，這會產生更清晰的錯誤訊息。例如，當函式庫不支援所需的 Java 版本時。實際效果是，現在所有 平台相依性 都必須宣告為此類相依性。以前，當 platform() 關鍵字省略用於本機平台或使用 Gradle 模組元資料發布的平台時，平台相依性也會意外地運作。

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 服務透過服務注入提供給工作人員動作。此服務允許可變狀態外洩到工作人員動作中，並引進一種方法，讓依賴關係在工作人員動作中保持未宣告狀態。

ProjectLayout 已從可用服務中移除。使用 ProjectLayout 的工作人員動作應改為注入 projectDirectory 或 buildDirectory 作為參數。

從 Gradle 6.2 開始，Gradle 會在您上傳前執行健全性檢查，以確保您不會上傳過期的檔案 (由其他組建產生的檔案)。這會對使用 components.java 組件上傳的 Spring Boot 應用程式造成問題

這是因為 Spring Boot 應用程式會停用主要的 jar 任務，而組件預期它會存在。由於 bootJar 任務預設使用與主要 jar 任務相同的檔案，因此 Gradle 的先前版本會

解決方法是告訴 Gradle 要上傳什麼。如果您要上傳 bootJar，則需要設定傳出組態來執行此動作

或者，您可能想要重新啟用 jar 任務，並加入具有不同分類項的 bootJar。