將您的組建從 Gradle 8.x 升級到最新版本
本章提供您將 Gradle 8.x 建置遷移到最新 Gradle 版本所需資訊。如要從 Gradle 4.x、5.x、6.x 或 7.x 遷移,請先參閱舊版遷移指南。
我們建議所有使用者執行下列步驟
-
嘗試執行
gradle help --scan
並檢視產生的建置掃描的不建議使用檢視。這樣您就可以看到套用於您的建置的任何不建議使用警告。
或者,您可以執行
gradle help --warning-mode=all
以在主控台中查看不建議使用事項,儘管它可能不會報告太多詳細資訊。 -
更新您的外掛。
有些外掛會因這個新版本的 Gradle 而中斷,例如因為它們使用已移除或變更的內部 API。前一步驟將透過在當外掛嘗試使用 API 的不建議使用部分時發出不建議使用警告,來協助您找出潛在問題。
-
執行
gradle wrapper --gradle-version 8.7
以將專案更新至 8.7。 -
嘗試執行專案並使用疑難排解指南除錯任何錯誤。
從 8.6 及更早版本升級
潛在中斷變更
升級至 Kotlin 1.9.22
已將嵌入式 Kotlin 更新至 Kotlin 1.9.22。
升級至 Apache SSHD 2.10.0
已將 Apache SSHD 從 2.0.0 更新至 2.10.0。
替換並升級 JSch
JSch 已被 com.github.mwiede:jsch
取代,並從 0.1.55 更新至 0.2.16
升級至 Eclipse JGit 5.13.3
已將 Eclipse JGit 從 5.7.0 更新至 5.13.3。
這包括重新設計 Gradle 設定 JGit 以進行 SSH 作業的方式,方法是從 JSch 移至 Apache SSHD。
升級至 Apache Commons Compress 1.25.0
已將 Apache Commons Compress 從 1.21 更新至 1.25.0。此變更可能會影響所產生 jar、zip 和其他檔案類型的檢查碼,因為所產生成品的元資料可能有所不同。
升級至 ASM 9.6
已將 ASM 從 9.5 升級至 9.6,以更好地支援多版本 jar。
已棄用
已棄用的外掛慣例註冊
自 Gradle 8.2 起,使用外掛慣例會發出警告。現在,註冊外掛慣例也會觸發已棄用警告。如需更多資訊,請參閱外掛慣例已棄用部分。
在 Kotlin DSL 中使用 "name"()
參照任務和網域物件
在 Kotlin DSL 中,可以使用 "name"()
符號,按名稱參照任務或其他網域物件。
有數種方式可以按名稱在容器中查詢元素
tasks {
"wrapper"() // 1 - returns TaskProvider<Task>
"wrapper"(Wrapper::class) // 2 - returns TaskProvider<Wrapper>
"wrapper"(Wrapper::class) { // 3 - configures a task named wrapper of type Wrapper
}
"wrapper" { // 4 - configures a task named wrapper of type Task
}
}
第一個符號已棄用,且將在 Gradle 9.0 中移除。請勿使用 "name"()
參照任務或網域物件,請改用 named("name")
或其他受支援的符號。
上述範例會寫成
tasks {
named("wrapper") // returns TaskProvider<Task>
}
Groovy DSL 建置指令碼和 Gradle API 不受此影響。
已棄用的無效 URL 解碼行為
在 Gradle 8.3 之前,Gradle 會使用接受無效 URL 並不當解碼其他 URL 的演算法,解碼提供給 Project.uri(Object)
的 CharSequence
。現在,Gradle 使用 URI
類別來剖析和解碼 URL,但如果發生錯誤,則會改用舊有行為。
自 Gradle 9.0 起,將移除此舊有行為,並改為擲回錯誤。
若要修正已棄用警告,需要舊有行為的無效 URL 應重新編碼為有效的 URL,如下列範例所示
原始輸入 | 新輸入 | 原因 |
---|---|---|
|
|
|
|
|
沒有架構時,路徑會原樣使用,不進行解碼。 |
|
URL 中不允許有空白。 |
|
|
已棄用的 SelfResolvingDependency
SelfResolvingDependency
介面已標示為棄用,並將在 Gradle 9.0 中移除。此類型可追溯至 Gradle 的第一個版本,其中一些相依性可以獨立解析。現在,所有相依性都應使用 Configuration
作為相依性圖的一部分來解析。
目前,ProjectDependency
和 FileCollectionDependency
實作此介面。在 Gradle 9.0 中,這些類型將不再實作 SelfResolvingDependency
。相反地,它們都將直接實作 Dependency
。
因此,ProjectDependency
和 FileCollectionDependency
的下列方法將不再可用
-
resolve
-
resolve(boolean)
-
getBuildDependencies
考慮下列展示已棄用介面及其替換項的指令碼
plugins {
id("java-library")
}
dependencies {
implementation(files("bar.txt"))
implementation(project(":foo"))
}
tasks.register("resolveDeprecated") {
// Wire build dependencies (calls getBuildDependencies)
dependsOn(configurations["implementation"].dependencies.toSet())
// Resolve dependencies
doLast {
configurations["implementation"].dependencies.withType<FileCollectionDependency>() {
assert(resolve().map { it.name } == listOf("bar.txt"))
assert(resolve(true).map { it.name } == listOf("bar.txt"))
}
configurations["implementation"].dependencies.withType<ProjectDependency>() {
// These methods do not even work properly.
assert(resolve().map { it.name } == listOf<String>())
assert(resolve(true).map { it.name } == listOf<String>())
}
}
}
tasks.register("resolveReplacement") {
val conf = configurations["runtimeClasspath"]
// Wire build dependencies
dependsOn(conf)
// Resolve dependencies
val files = conf.files
doLast {
assert(files.map { it.name } == listOf("bar.txt", "foo.jar"))
}
}
從 8.5 及更早版本升級
潛在的重大變更
升級至 JaCoCo 0.8.11
JaCoCo 已更新至 0.8.11。
DependencyAdder
已重新命名為 DependencyCollector
正在孵化的 DependencyAdder
介面已重新命名為 DependencyCollector
。已將 getDependencies
方法新增至介面,該方法會傳回所有已宣告的相依性。
已棄用
已棄用使用 main
來源組呼叫 registerFeature
在 java
擴充功能上使用 main
來源組呼叫 registerFeature
已棄用,且將在 Gradle 9.0 中變更行為。
目前,在呼叫 usingSourceSet
時建立的功能,其主要來源設定與在呼叫 usingSourceSet
時建立的功能不同,且使用任何其他來源設定。先前,在使用主要來源設定時,會建立新的 implementation
、compileOnly
、runtimeOnly
、api
和 compileOnlyApi
設定檔,且主要來源設定的編譯和執行時期類別路徑會設定為延伸這些設定檔。
從 Gradle 9.0 開始,主要來源設定會像任何其他來源設定一樣處理。在套用 java-library
外掛程式(或套用 java
外掛程式的任何其他外掛程式)時,使用主要來源設定呼叫 usingSourceSet
會擲回例外狀況。這是因為 java
外掛程式已設定主要功能。只有在未套用 java
外掛程式時,呼叫 usingSourceSet
才會允許主要來源設定。
目前使用主要來源設定註冊功能的程式碼,如下所示
plugins {
id("java-library")
}
java {
registerFeature("feature") {
usingSourceSet(sourceSets["main"])
}
}
plugins {
id("java-library")
}
java {
registerFeature("feature") {
usingSourceSet(sourceSets.main)
}
}
應該為功能建立一個獨立的來源設定,並使用該來源設定註冊功能
plugins {
id("java-library")
}
sourceSets {
create("feature")
}
java {
registerFeature("feature") {
usingSourceSet(sourceSets["feature"])
}
}
plugins {
id("java-library")
}
sourceSets {
feature
}
java {
registerFeature("feature") {
usingSourceSet(sourceSets.feature)
}
}
已棄用的發佈人工製品相依性,其明確名稱與 Maven 儲存庫中的人工製品 ID 不同
已棄用發佈相依性,其明確人工製品名稱與相依性的 artifactId
不同,至 Maven 儲存庫。在發佈至 Ivy 儲存庫時,此行為仍被允許。這會在 Gradle 9.0 中造成錯誤。
目前,在發佈至 Maven 儲存庫時,Gradle 會將以下相依性解釋為已使用座標 org:notfoo:1.0
宣告。
dependencies {
implementation("org:foo:1.0") {
artifact {
name = "notfoo"
}
}
}
dependencies {
implementation("org:foo:1.0") {
artifact {
name = "notfoo"
}
}
}
此相依性應宣告為
dependencies {
implementation("org:notfoo:1.0")
}
dependencies {
implementation("org:notfoo:1.0")
}
已棄用的 ArtifactIdentifier
ArtifactIdentifier
類別已棄用,並將在 Gradle 9.0 中移除。
已棄用在觀察後變更 DependencyCollector
相依性
從 Gradle 9.0 開始,在觀察 DependencyCollector 中的來源相依性後,變更這些相依性會造成錯誤。DependencyCollector
介面用於在測試套件 DSL 中宣告相依性。
考慮以下範例,其中測試套件的相依性在觀察後會產生突變
plugins {
id("java-library")
}
testing.suites {
named<JvmTestSuite>("test") {
dependencies {
// Dependency is declared on a `DependencyCollector`
implementation("com:foo")
}
}
}
configurations.testImplementation {
// Calling `all` here realizes/observes all lazy sources, including the `DependencyCollector`
// from the test suite block. Operations like resolving a configuration similarly realize lazy sources.
dependencies.all {
if (this is ExternalDependency && group == "com" && name == "foo" && version == null) {
// Dependency is mutated after observation
version {
require("2.0")
}
}
}
}
在上述範例中,建置邏輯使用反覆運算和突變來嘗試設定特定相依性的預設版本(如果尚未設定版本)。如上述範例的建置邏輯會在解析已宣告的相依性時造成挑戰,因為報告工具會顯示此相依性,就好像使用者已宣告版本為「2.0」,即使他們從未宣告過。建置邏輯可以宣告相依性座標上的preferred
版本約束,以避免反覆運算和突變。如果未宣告其他版本,這將允許相依性管理引擎使用約束上宣告的版本。
考慮以下範例,其中使用不分青紅皂白的preferred版本約束取代上述反覆運算
dependencies {
constraints {
testImplementation("com:foo") {
version {
prefer("2.0")
}
}
}
}
從 8.4 及更早版本升級
潛在中斷變更
升級至 Kotlin 1.9.20
已將嵌入式 Kotlin 更新至Kotlin 1.9.20。
Groovy 任務慣例的變更
groovy-base
外掛現在負責設定所有 GroovyCompile
任務的來源和目標相容性版本慣例。
如果您在未套用 grooy-base
的情況下使用此任務,則必須手動設定這些任務的相容性版本。一般而言,只要使用 Groovy 語言任務,就應套用 groovy-base
外掛。
Provider.filter
傳遞至 Provider.filter
的引數類型已從 Predicate
變更為 Spec
,以提供更一致的 API。此變更不應影響使用 lambda 運算式與 Provider.filter
的任何使用者。不過,如果外掛作者未使用 SAM 轉換建立 lambda,這可能會影響他們。
不建議使用的項目
org.gradle.util
套件中不建議使用的成員現在會報告其不建議使用
這些成員將在 Gradle 9.0 中移除
-
VersionNumber.parse(String)
-
VersionNumber.compareTo(VersionNumber)
依賴已解析組態,已棄用
解析 Configuration
時,有時可以選擇將同一個組態選為變異。組態應使用於一個目的(解析、使用或相依宣告),因此這只有在組態標示為可使用和可解析時才會發生。
這可能會導致混淆的循環相依圖,因為正在解析的組態用於兩個不同的目的。
為避免這個問題,外掛應將所有可解析的組態標示為 canBeConsumed=false
,或在建立用於解析的組態時使用 resolvable(String)
組態工廠方法。
在 Gradle 9.0 中,將不再允許以這種方式使用組態,否則會導致錯誤。
包含沒有現有目錄的專案
如果將專案新增到建置中,但相關聯的 projectDir
不存在或不可寫入,Gradle 會發出警告。從版本 9.0 開始,如果專案目錄不存在或唯讀,Gradle 將不會執行建置。如果您打算動態合成專案,請務必也為它們建立目錄
include("project-without-directory")
project(":project-without-directory").projectDir.mkdirs()
include 'project-without-directory'
project(":project-without-directory").projectDir.mkdirs()
從 8.3 及更早版本升級
潛在的重大變更
升級至 Kotlin 1.9.10
已將內嵌 Kotlin 更新至 Kotlin 1.9.10。
XML 解析現在需要較新的解析器
Gradle 8.4 現在會設定 XML 解析器,並啟用安全功能。如果您的建置邏輯依賴於不支援安全解析的舊式 XML 解析器,您的建置現在可能會失敗。如果您遇到失敗,請檢查並更新或移除對舊式 XML 解析器的任何依賴關係。
如果您無法升級建置邏輯相依項中的 XML 解析器,您可以強制使用 JVM 內建的 XML 解析器。例如,在 OpenJDK 中,這可以透過將下列內容新增至 gradle.properties
來完成
systemProp.javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
systemProp.javax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
systemProp.javax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl
請參閱 CVE-2023-42445 公告,以取得更多詳細資訊和在先前 Gradle 版本中啟用安全 XML 處理的方法。
使用自訂 JEE 1.3 描述子的 EAR 外掛程式
Gradle 8.4 在分析 XML 文件時禁止使用外部 XML 實體。如果您使用 EAR 外掛程式,並透過 EAR 外掛程式的 DSL 設定 application.xml
描述子,並使用 withXml {}
自訂描述子,並在自訂區塊中使用 asElement{}
,則建置現在會因為安全性原因而失敗。
plugins {
id("ear")
}
ear {
deploymentDescriptor {
version = "1.3"
withXml {
asElement()
}
}
}
plugins {
id("ear")
}
ear {
deploymentDescriptor {
version = "1.3"
withXml {
asElement()
}
}
}
如果您碰巧使用 asNode()
而不是 asElement()
,則不會有任何變更,因為 asNode()
僅忽略外部 DTD。
您可以透過執行建置,並將 javax.xml.accessExternalDTD
系統屬性設定為 http
來解決此問題。
在命令列中,將此內容新增至您的 Gradle 呼叫
-Djavax.xml.accessExternalDTD=http
若要使此解決方法持續存在,請將下列行新增至您的 gradle.properties
systemProp.javax.xml.accessExternalDTD=http
請注意,這會為整個建置 JVM 啟用對外部 DTD 的 HTTP 存取。請參閱 JAXP 文件 以取得更多詳細資料。
不建議使用
不建議使用的 GenerateMavenPom
方法
GenerateMavenPom
上的下列方法已不建議使用,並將在 Gradle 9.0 中移除。它們從未打算成為公開 API。
-
getVersionRangeMapper
-
withCompileScopeAttributes
-
withRuntimeScopeAttributes
從 8.2 及更早版本升級
潛在的重大變更
不建議使用的 Project.buildDir
可能導致指令碼編譯失敗
隨著 Project.buildDir
不再建議使用,如果使用不建議使用的欄位,則將警告編譯為錯誤的建置指令碼可能會失敗。
請參閱 不建議使用的條目 以取得詳細資料。
TestLauncher
API 不再忽略建置失敗
TestLauncher
介面是工具 API 的一部分,專門用於執行測試。它是僅能啟動任務的 BuildLauncher
的邏輯延伸。已回報其行為中的差異:如果執行相同的失敗測試,BuildLauncher
會回報建置失敗,但 TestLauncher
卻不會。最初,這是為了繼續執行並在所有測試任務中執行測試,而不是在第一次失敗時停止的設計決策。同時,這種行為可能會讓使用者感到困惑,因為他們可能會在成功的建置中遇到失敗的測試。為了讓這兩個 API 更為一致,我們也讓 TestLauncher
失敗建置,這是一個潛在的重大變更。若要繼續測試執行,即使測試任務失敗,工具 API 用戶端應明確將 --continue
傳遞給建置。
使用 ArtifactView
和 ArtifactCollection
修復變體選取行為
用於選取不同人工製品或檔案的相依解析 API (Configuration.getIncoming().artifactView { }
和 Configuration.getIncoming().getArtifacts()
) 會擷取底層 `Configuration` 屬性的不可變副本,以用於變體選取。如果在呼叫這些方法後變更了 `Configuration` 的屬性,則這些方法選取的人工製品可能會出乎意料。
考慮在建立 ArtifactView
後變更 Configuration
上的屬性集合的情況。
tasks {
myTask {
inputFiles.from(configurations.classpath.incoming.artifactView {
attributes {
// Add attributes to select a different type of artifact
}
}.files)
}
}
configurations {
classpath {
attributes {
// Add more attributes to the configuration
}
}
}
myTask
的 inputFiles
屬性使用人工製品檢視從組態 classpath
中選取不同類型的人工製品。由於人工製品檢視是在將屬性新增到組態之前建立的,因此 Gradle 無法選取正確的人工製品。
有些建置可能已透過將其他屬性也放入人工製品檢視中來解決此問題。這不再是必要的。
升級到 Kotlin 1.9.0
已將內嵌 Kotlin 從 1.8.20 更新到 Kotlin 1.9.0。Kotlin DSL 的 Kotlin 語言和 API 層級仍設定為 1.8,以維持向後相容性。請參閱 Kotlin 1.8.22 和 Kotlin 1.8.21 的發行說明。
Kotlin 1.9 已不再支援 Kotlin 語言和 API 層級 1.3。如果您使用此 Gradle 版本建置以 Kotlin 編寫的 Gradle 外掛程式,且需要支援 Gradle <7.0,則您需要堅持使用 Kotlin Gradle 外掛程式 <1.9.0,並將 Kotlin 語言和 API 層級設定為 1.3。請參閱 相容性矩陣,以取得有關其他版本的詳細資訊。
即時評估 Configuration
屬性
Gradle 8.3 會更新 JVM 組態的 org.gradle.libraryelements
和 org.gradle.jvm.version
屬性,使其在建立時即存在,而不是像以前一樣,僅在組態已解析或使用後才會存在。特別是,org.gradle.jvm.version
的值依賴於專案設定的工具鏈,這表示查詢此屬性的值會確定專案的 Java 工具鏈的值。
即時查詢 JVM 組態屬性的外掛程式或建置邏輯現在可能會導致專案的 Java 工具鏈比以前更早確定。在工具鏈確定後嘗試修改工具鏈會導致類似下列錯誤訊息
The value for property 'implementation' is final and cannot be changed any further.
The value for property 'languageVersion' is final and cannot be changed any further.
The value for property 'vendor' is final and cannot be changed any further.
當外掛程式或建置邏輯即時查詢現有 JVM 組態的屬性,以建立具有相同屬性的新組態時,可能會發生這種情況。以前,此邏輯會完全略過上述兩個屬性,而現在相同的邏輯會複製屬性並確定專案的 Java 工具鏈。為避免提早確定工具鏈,應更新屬性複製邏輯,以延遲查詢來源組態的屬性
fun <T> copyAttribute(attribute: Attribute<T>, from: AttributeContainer, to: AttributeContainer) =
to.attributeProvider<T>(attribute, provider { from.getAttribute(attribute)!! })
val source = configurations["runtimeClasspath"].attributes
configurations {
create("customRuntimeClasspath") {
source.keySet().forEach { key ->
copyAttribute(key, source, attributes)
}
}
}
def source = configurations.runtimeClasspath.attributes
configurations {
customRuntimeClasspath {
source.keySet().each { key ->
attributes.attributeProvider(key, provider { source.getAttribute(key) })
}
}
}
不建議使用的項目
不建議使用的 Project.buildDir
將由 Project.layout.buildDirectory
取代
Project.buildDir
屬性已不建議使用。它使用即時 API,如果在建置邏輯中讀取值,然後稍後修改值,則會有排序問題。它可能會導致輸出最終出現在不同的位置。
它已被 DirectoryProperty
取代,位於 Project.layout.buildDirectory
。請參閱 ProjectLayout
介面以取得詳細資訊。
請注意,在此階段,如果您仍使用 Project.buildDir
,Gradle 仍不會列印不建議使用的警告。我們知道這是一個重大的變更,並希望先給予主要外掛的作者時間來停止使用它。
從 File
切換到 DirectoryProperty
需要在建置邏輯中進行調整。主要的影響是您無法在 String
內部使用屬性來擴充它。相反地,您應該利用 dir
和 file
方法來計算您要的位置。
以下是建立檔案的範例,其中下列內容
// Returns a java.io.File
file("$buildDir/myOutput.txt")
// Returns a java.io.File
file("$buildDir/myOutput.txt")
應替換為
// Compatible with a number of Gradle lazy APIs that accept also java.io.File
val output: Provider<RegularFile> = layout.buildDirectory.file("myOutput.txt")
// If you really need the java.io.File for a non lazy API
output.get().asFile
// Or a path for a lazy String based API
output.map { it.asFile.path }
// Compatible with a number of Gradle lazy APIs that accept also java.io.File
Provider<RegularFile> output = layout.buildDirectory.file("myOutput.txt")
// If you really need the java.io.File for a non lazy API
output.get().asFile
// Or a path for a lazy String based API
output.map { it.asFile.path }
以下是建立目錄的另一個範例,其中包含下列內容
// Returns a java.io.File
file("$buildDir/outputLocation")
// Returns a java.io.File
file("$buildDir/outputLocation")
應替換為
// Compatible with a number of Gradle APIs that accept a java.io.File
val output: Provider<Directory> = layout.buildDirectory.dir("outputLocation")
// If you really need the java.io.File for a non lazy API
output.get().asFile
// Or a path for a lazy String based API
output.map { it.asFile.path }
// Compatible with a number of Gradle APIs that accept a java.io.File
Provider<Directory> output = layout.buildDirectory.dir("outputLocation")
// If you really need the java.io.File for a non lazy API
output.get().asFile
// Or a path for a lazy String based API
output.map { it.asFile.path }
已棄用的 ClientModule
相依性
ClientModule
相依性已棄用,並將在 Gradle 9.0 中移除。
Client 模組相依性最初旨在允許建置覆寫外部相依性的不正確或遺失元件資料,方法是定義本機資料。此功能已由 元件資料規則 取代。
考慮下列 client 模組相依性範例
dependencies {
implementation(module("org:foo:1.0") {
dependency("org:bar:1.0")
module("org:baz:1.0") {
dependency("com:example:1.0")
}
})
}
dependencies {
implementation module("org:foo:1.0") {
dependency "org:bar:1.0"
module("org:baz:1.0") {
dependency "com:example:1.0"
}
}
}
這可以用下列元件資料規則取代
@CacheableRule
abstract class AddDependenciesRule @Inject constructor(val dependencies: List<String>) : ComponentMetadataRule {
override fun execute(context: ComponentMetadataContext) {
listOf("compile", "runtime").forEach { base ->
context.details.withVariant(base) {
withDependencies {
dependencies.forEach {
add(it)
}
}
}
}
}
}
dependencies {
components {
withModule<AddDependenciesRule>("org:foo") {
params(listOf(
"org:bar:1.0",
"org:baz:1.0"
))
}
withModule<AddDependenciesRule>("org:baz") {
params(listOf("com:example:1.0"))
}
}
implementation("org:foo:1.0")
}
@CacheableRule
abstract class AddDependenciesRule implements ComponentMetadataRule {
List<String> dependencies
@Inject
AddDependenciesRule(List<String> dependencies) {
this.dependencies = dependencies
}
@Override
void execute(ComponentMetadataContext context) {
["compile", "runtime"].each { base ->
context.details.withVariant(base) {
withDependencies {
dependencies.each {
add(it)
}
}
}
}
}
}
dependencies {
components {
withModule("org:foo", AddDependenciesRule) {
params([
"org:bar:1.0",
"org:baz:1.0"
])
}
withModule("org:baz", AddDependenciesRule) {
params(["com:example:1.0"])
}
}
implementation "org:foo:1.0"
}
最早支援的 Develocity 外掛程式版本為 3.13.1
從 Gradle 9.0 開始,最早支援的 Develocity 外掛程式版本為 3.13.1。套用時將略過 3.0 到 3.13 的外掛程式版本。
升級到 Develocity 外掛程式 3.13.1 或更新版本。您可以在 Gradle 外掛程式入口網站 找到 最新可用版本。您可以在 這裡 找到有關相容性的更多資訊。
從 8.1 及更早版本升級
潛在破壞性變更
升級到 Kotlin 1.8.20
已將嵌入式 Kotlin 更新為 Kotlin 1.8.20。如需更多資訊,請參閱 Kotlin 1.8.20 的新功能。
請注意,Kotlin 編譯避免已知問題可能會導致 compileKotlin
任務中的 OutOfMemory
例外,如果編譯類別路徑包含非常大的 JAR 檔案。這適用於套用 Kotlin 外掛程式 v1.8.20 或 kotlin-dsl
外掛程式的建置。
您可以在 gradle.properties
檔案中停用 Kotlin 編譯避免來解決此問題
kotlin.incremental.useClasspathSnapshot=false
請參閱 KT-57757 以取得更多資訊。
升級至 CodeNarc 3.2.0
CodeNarc 的預設版本已更新至 CodeNarc 3.2.0。
升級至 JaCoCo 0.8.9
JaCoCo 已更新至 0.8.9。
外掛相容性變更
使用 Kotlin DSL 函式 Project.the<T>()
、Project.the(KClass)
或 Project.configure<T> {}
編譯的 Gradle >= 8.2 外掛無法在 Gradle ⇐ 6.1 上執行。
延遲或避免某些任務的設定
在執行相依性解析時,Gradle 會建立可用 Configuration 的內部表示。這需要檢查所有設定和成品。處理任務建立的成品會導致這些任務實現並設定。
此內部表示現在建立得更為延遲,這可能會變更任務設定的順序。有些任務可能永遠不會設定。
此變更可能會導致依賴特定順序的程式碼路徑不再運作,例如根據特定屬性的存在條件式地加入屬性至設定。
這影響了 bnd 外掛和 JUnit5 建置。
我們建議不要從其他可能未設定的領域物件的設定區塊修改領域物件(設定、來源組、任務等)。
例如,避免執行類似下列動作
configurations {
val myConfig = create("myConfig")
}
tasks.register("myTask") {
// This is not safe, as the execution of this block may not occur, or may not occur in the order expected
configurations["myConfig"].attributes {
attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage::class.java, Usage.JAVA_RUNTIME))
}
}
不建議使用的功能
CompileOptions
方法不建議使用
CompileOptions
上的下列方法不建議使用
-
getAnnotationProcessorGeneratedSourcesDirectory()
-
setAnnotationProcessorGeneratedSourcesDirectory(檔案)
-
setAnnotationProcessorGeneratedSourcesDirectory(提供者<檔案>)
這些方法的目前使用方式應移轉到 DirectoryProperty getGeneratedSourceOutputDirectory()
使用組態不正確
當呼叫 組態 的方法與組態的預期用途不一致時,Gradle 現在會在執行階段發出警告。
此變更是一項較大規模的持續性工作的一部分,目的是讓組態的預期行為更一致且可預測,並進一步提升速度和記憶體改善。
目前,下列方法只能呼叫這些列出的允許用途
-
resolve()
- 僅限可解析組態 -
files(Closure)
、files(Spec)
、files(Dependency…)
、fileCollection(Spec)
、fileCollection(Closure)
、fileCollection(Dependency…)
- 僅限可解析組態 -
getResolvedConfigurations()
- 僅限可解析組態 -
defaultDependencies(Action)
- 僅限可宣告組態 -
shouldResolveConsistentlyWith(Configuration)
- 僅限可解析組態 -
disableConsistentResolution()
- 僅限可解析組態 -
getDependencyConstraints()
- 僅限可宣告組態 -
copy()
、copy(Spec)
、copy(Closure)
、copyRecursive()
、copyRecursive(Spec)
、copyRecursive(Closure)
- 僅限可解析組態
預期用途會記載在 Configuration
介面的 Javadoc 中。此清單可能會在未來的版本中增加。
從 Gradle 9.0 開始,將禁止與預期用途不一致地使用組態。
另請注意,雖然目前沒有限制,但 getDependencies()
方法實際上僅供與可宣告組態搭配使用。getAllDependencies()
方法會擷取組態和任何超組態上宣告的所有相依性,不會限制為任何特定用途。
已棄用的插件慣例存取
慣例的概念已過時,並由 擴充功能 取代,以提供自訂 DSL。
為了在 Gradle API 中反映這一點,下列元素已棄用
-
org.gradle.api.internal.HasConvention
Gradle Core 外掛仍會註冊其慣例,以維持向後相容性,除了其擴充功能外。
存取這些慣例及其屬性已被棄用。現在這麼做會發出棄用警告。這將在 Gradle 9.0 中變成錯誤。您應優先存取擴充功能及其屬性。
有關特定範例,請參閱下一個區段。
著名的社群外掛已移轉至使用擴充功能來提供自訂 DSL。其中一些外掛仍會註冊慣例以維持向後相容性。註冊慣例尚未發出棄用警告,以提供移轉時間。未來的 Gradle 版本會這麼做。
另請注意,使用 Kotlin DSL 函數 Project.the<T>()
、Project.the(KClass)
或 Project.configure<T> {}
編譯的 Gradle ⇐ 8.1 外掛,在 Gradle >= 8.2 上執行時會發出棄用警告。若要修正此問題,應使用 Gradle >= 8.2 重新編譯這些外掛,或改為使用 extensions.getByType<T>()
直接存取擴充功能。
已棄用的 base
外掛慣例
base
外掛提供的慣例屬性已棄用,並預計在 Gradle 9.0 中移除。有關更廣泛的背景,請參閱 有關外掛慣例棄用的區段。
慣例已由 BasePluginExtension 支援的 base { }
組態區塊取代。舊的慣例物件定義 distsDirName
、libsDirName
和 archivesBaseName
屬性,並提供簡單的 getter 和 setter 方法。這些方法僅在擴充功能中提供,以維持向後相容性。建置指令碼應僅使用 Property
類型的屬性
plugins {
base
}
base {
archivesName.set("gradle")
distsDirectory.set(layout.buildDirectory.dir("custom-dist"))
libsDirectory.set(layout.buildDirectory.dir("custom-libs"))
}
plugins {
id 'base'
}
base {
archivesName = "gradle"
distsDirectory = layout.buildDirectory.dir('custom-dist')
libsDirectory = layout.buildDirectory.dir('custom-libs')
}
已棄用的 application
外掛慣例
application
外掛提供的慣例屬性已棄用,並預計在 Gradle 9.0 中移除。有關更廣泛的背景,請參閱 有關外掛慣例棄用的區段。
下列程式碼現在會發出棄用警告
plugins {
application
}
applicationDefaultJvmArgs = listOf("-Dgreeting.language=en") // Accessing a convention
plugins {
id 'application'
}
applicationDefaultJvmArgs = ['-Dgreeting.language=en'] // Accessing a convention
應改為使用由 JavaApplication 支援的 application { }
組態區塊
plugins {
application
}
application {
applicationDefaultJvmArgs = listOf("-Dgreeting.language=en")
}
plugins {
id 'application'
}
application {
applicationDefaultJvmArgs = ['-Dgreeting.language=en']
}
已棄用的 java
外掛慣例
java
外掛提供的慣例屬性已棄用,並排定在 Gradle 9.0 中移除。關於更廣泛的背景,請參閱 關於外掛慣例棄用的章節。
下列程式碼現在會發出棄用警告
plugins {
id("java")
}
configure<JavaPluginConvention> { // Accessing a convention
sourceCompatibility = JavaVersion.VERSION_18
}
plugins {
id 'java'
}
sourceCompatibility = 18 // Accessing a convention
這應該變更為使用 java { }
設定區塊,改由 JavaPluginExtension 支援
plugins {
id("java")
}
java {
sourceCompatibility = JavaVersion.VERSION_18
}
plugins {
id 'java'
}
java {
sourceCompatibility = JavaVersion.VERSION_18
}
已棄用的 war
外掛慣例
war
外掛提供的慣例屬性已棄用,並排定在 Gradle 9.0 中移除。關於更廣泛的背景,請參閱 關於外掛慣例棄用的章節。
下列程式碼現在會發出棄用警告
plugins {
id("war")
}
configure<WarPluginConvention> { // Accessing a convention
webAppDirName = "src/main/webapp"
}
plugins {
id 'war'
}
webAppDirName = 'src/main/webapp' // Accessing a convention
用戶端應直接設定 war
工作。此外,tasks.withType(War.class).configureEach(…) 可用於設定 War
類型的每個工作。
plugins {
id("war")
}
tasks.war {
webAppDirectory.set(file("src/main/webapp"))
}
plugins {
id 'war'
}
war {
webAppDirectory = file('src/main/webapp')
}
已棄用的 ear
外掛慣例
ear
外掛提供的慣例屬性已棄用,並排定在 Gradle 9.0 中移除。關於更廣泛的背景,請參閱 關於外掛慣例棄用的章節。
下列程式碼現在會發出棄用警告
plugins {
id("ear")
}
configure<EarPluginConvention> { // Accessing a convention
appDirName = "src/main/app"
}
plugins {
id 'ear'
}
appDirName = 'src/main/app' // Accessing a convention
用戶端應直接設定 ear
工作。此外,tasks.withType(Ear.class).configureEach(…) 可用於設定 Ear
類型的每個工作。
plugins {
id("ear")
}
tasks.ear {
appDirectory.set(file("src/main/app"))
}
plugins {
id 'ear'
}
ear {
appDirectory = file('src/main/app') // use application metadata found in this folder
}
已棄用的 project-report
外掛慣例
project-reports
外掛提供的慣例屬性已棄用,並排定在 Gradle 9.0 中移除。關於更廣泛的背景,請參閱 關於外掛慣例棄用的章節。
下列程式碼現在會發出棄用警告
plugins {
`project-report`
}
configure<ProjectReportsPluginConvention> {
projectReportDirName = "custom" // Accessing a convention
}
plugins {
id 'project-report'
}
projectReportDirName = "custom" // Accessing a convention
改為設定您的報告工作
plugins {
`project-report`
}
tasks.withType<HtmlDependencyReportTask>() {
projectReportDirectory.set(project.layout.buildDirectory.dir("reports/custom"))
}
plugins {
id 'project-report'
}
tasks.withType(HtmlDependencyReportTask) {
projectReportDirectory = project.layout.buildDirectory.dir("reports/custom")
}
多餘的設定使用啟用
對已允許該使用方式的設定呼叫 setCanBeConsumed(boolean)
或 setCanBeResolved(boolean)
已棄用。
此棄用旨在協助使用者識別不必要的設定使用修改。
依賴自動測試架構實作相依性
在某些情況下,Gradle 會從 Gradle 發行版載入 JVM 測試架構相依性,以執行測試。此現有行為可能會導致測試類別路徑上的測試架構相依性版本衝突。為了避免這些衝突,此行為已棄用,並將在 Gradle 9.0 中移除。使用 TestNG 的測試不受影響。
為了準備此行為變更,請明確宣告所需的相依性,或移轉到 測試套件,其中這些相依性會自動管理。
手動宣告相依性
在沒有測試套件的情況下,必須手動在測試執行時期類別路徑上宣告相依性
-
如果使用 JUnit 5,除了現有的測試引擎的
implementation
相依性外,還需要對junit-platform-launcher
宣告明確的runtimeOnly
相依性。 -
如果使用 JUnit 4,只需要現有的
junit
4 的implementation
相依性。 -
如果使用 JUnit 3,除了對
junit
3 的compileOnly
相依性外,還需要對junit
4 宣告測試runtimeOnly
相依性。
dependencies {
// If using JUnit Jupiter
testImplementation("org.junit.jupiter:junit-jupiter:5.9.2")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
// If using JUnit Vintage
testCompileOnly("junit:junit:4.13.2")
testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.9.2")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
// If using JUnit 4
testImplementation("junit:junit:4.13.2")
// If using JUnit 3
testCompileOnly("junit:junit:3.8.2")
testRuntimeOnly("junit:junit:4.13.2")
}
dependencies {
// If using JUnit Jupiter
testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
// If using JUnit Vintage
testCompileOnly 'junit:junit:4.13.2'
testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.9.2'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
// If using JUnit 4
testImplementation 'junit:junit:4.13.2'
// If using JUnit 3
testCompileOnly 'junit:junit:3.8.2'
testRuntimeOnly 'junit:junit:4.13.2'
}
BuildIdentifier
和 ProjectComponentSelector
方法已棄用
BuildIdentifier
上的下列方法已棄用
-
getName()
-
isCurrentBuild()
您可以使用這些方法來區分具有相同名稱但來自不同建置的不同專案元件。但是,對於某些複合建置設定,這些方法無法提供足夠的資訊來保證唯一性。
這些方法的目前使用方式應移轉到 BuildIdentifier.getBuildPath()
。
同樣地,方法 ProjectComponentSelector.getBuildName()
已棄用。請改用 ProjectComponentSelector.getBuildPath()
。
從 8.0 及更早版本升級
CACHEDIR.TAG 檔案建立在全域快取目錄中
Gradle 現在會在一些全域快取目錄中發出 CACHEDIR.TAG
檔案,如 directory_layout.html 中所指定。
這可能會導致這些目錄不再被一些工具搜尋或備份。若要停用它,請在 Gradle 使用者主目錄中使用 初始化指令碼 中使用以下程式碼
beforeSettings {
caches {
// Disable cache marking for all caches
markingStrategy.set(MarkingStrategy.NONE)
}
}
beforeSettings { settings ->
settings.caches {
// Disable cache marking for all caches
markingStrategy = MarkingStrategy.NONE
}
}
組態快取選項已重新命名
在此版本中,組態快取功能已從孵化階段提升至穩定階段,因此所有原本在功能文件 (其名稱中包含 unsafe
部分,例如 org.gradle.unsafe.configuration-cache
) 中提到的屬性都已重新命名,在某些情況下,只需移除 unsafe
部分即可。
孵化階段屬性 | 已完成屬性 |
---|---|
|
|
|
|
|
|
請注意,原始的 org.gradle.unsafe.configuration-cache…
屬性在此版本中仍會受到重視,如果使用它們,不會產生任何警告,但它們將在未來的版本中棄用並移除。
潛在的重大變更
Kotlin DSL 指令碼發出編譯警告
來自 Kotlin DSL 指令碼的編譯警告會印出至主控台輸出。例如,在 Kotlin DSL 中使用已棄用的 API 會在每次編譯指令碼時發出警告。
如果您正在使用 Gradle 建置的主控台輸出,這是一個潛在的重大變更。
套用 kotlin-dsl
外掛時,組態 Kotlin 編譯器選項
如果您在套用 kotlin-dsl 外掛的專案上組態自訂 Kotlin 編譯器選項,您可能會遇到重大變更。
在之前的 Gradle 版本中,kotlin-dsl
外掛會在 afterEvaluate {} 上新增必要的編譯器參數。現在 Kotlin Gradle 外掛提供 延遲組態 屬性,我們的 kotlin-dsl
外掛已改為將必要的編譯器參數直接新增至延遲屬性。因此,如果您正在設定 freeCompilerArgs
,kotlin-dsl
外掛現在會讓建置失敗,因為其必要的編譯器參數會被您的組態覆寫。
plugins {
`kotlin-dsl`
}
tasks.withType(KotlinCompile::class).configureEach {
kotlinOptions { // Deprecated non-lazy configuration options
freeCompilerArgs = listOf("-Xcontext-receivers")
}
}
使用上述設定會導致以下建置失敗
* What went wrong
Execution failed for task ':compileKotlin'.
> Kotlin compiler arguments of task ':compileKotlin' do not work for the `kotlin-dsl` plugin. The 'freeCompilerArgs' property has been reassigned. It must instead be appended to. Please use 'freeCompilerArgs.addAll(\"your\", \"args\")' to fix this.
您必須將此變更為將自訂編譯器參數新增至 Kotlin Gradle 外掛的 lazy 設定屬性,才能將它們附加至 kotlin-dsl
外掛所需的參數
plugins {
`kotlin-dsl`
}
tasks.withType(KotlinCompile::class).configureEach {
compilerOptions { // New lazy configuration options
freeCompilerArgs.addAll("-Xcontext-receivers")
}
}
如果您已經新增至 freeCompilerArgs
,而不是設定其值,則不應發生建置失敗。
新增的 API 可能與現有的 Gradle DSL 程式碼衝突
當在 Gradle DSL 中的現有類型中新增新的屬性或方法時,它可能會與使用者程式碼中已使用的名稱衝突。
當名稱衝突發生時,一種解決方案是重新命名使用者程式碼中的元素。
這是 8.1 中可能導致與現有使用者程式碼發生名稱衝突的 API 新增的非詳盡清單。
在設定時間使用不受支援的 API 來啟動外部程序不再被允許,而且設定快取已啟用
自 Gradle 7.5 以來,使用 Project.exec
、Project.javaexec
以及標準 Java 和 Groovy API 在設定時間執行外部程序僅在啟用 功能預覽 STABLE_CONFIGURATION_CACHE
時才被視為錯誤。隨著設定快取在 Gradle 8.1 中提升為穩定功能,此錯誤會在不論功能預覽狀態如何的情況下被偵測到。設定快取章節 有更多詳細資訊,以協助移轉至新的基於提供者的 API,以便在設定時間執行外部程序。
不使用設定快取或僅在執行時間啟動外部程序的建置不受此變更影響。
不建議使用
變更核心外掛設定使用
設定的允許使用應在建立後不變。變更由 Gradle 核心外掛建立的設定上的允許使用已不建議使用。這包括呼叫下列任何 Configuration
方法
-
setCanBeConsumed(boolean)
-
setCanBeResolved(boolean)
這些方法現在會針對這些組態發出不建議使用的警告,但某些特殊情況除外,這些情況允許現有行為的熱門外掛程式。此規則尚未套用於分離組態或在建置指令碼和第三方外掛程式中建立的組態。呼叫 apiElements
或 runtimeElements
上的 setCanBeConsumed(false)
尚未不建議使用,以避免在使用某些熱門第三方外掛程式時發出警告。
此變更為持續進行的更大專案的一部分,目的是讓組態的預期行為更一致且可預測,並在此 Gradle 領域中釋放更多速度和記憶體改善。
在 Gradle 9.0 中,變更組態建立後允許使用的功能將會移除。
保留的組態名稱
建立分離組態時,組態名稱「detachedConfiguration」和「detachedConfigurationX」(其中 X 為任意整數)保留供內部使用。
在 Gradle 9.0 中,建立具有這些名稱的非分離組態的功能將會移除。
在沒有 java
元件的情況下,呼叫 JavaPluginExtension
上的選取方法
從 Gradle 8.1 開始,在沒有預設 java
元件的情況下,呼叫 JavaPluginExtension
上的下列任何方法都已不建議使用
-
withJavadocJar()
-
withSourcesJar()
-
consistentResolution(Action)
此 java
元件是由 JavaPlugin
新增的,而 JavaPlugin
是由任何 Gradle JVM 外掛程式套用的,包括
-
java-library
-
application
-
groovy
-
scala
從 Gradle 9.0 開始,在沒有預設 java
元件的情況下,呼叫上述任何列出的方法將會變成錯誤。
WarPlugin#configureConfiguration(ConfigurationContainer)
從 Gradle 8.1 開始,呼叫 WarPlugin#configureConfiguration(ConfigurationContainer)
已不建議使用。此方法預計供內部使用,且從未預計作為公開介面的部分使用。
從 Gradle 9.0 開始,此方法將會移除,且不會替換。
依賴自訂測試任務的慣例
預設情況下,套用 java
外掛程式時,所有 Test
任務的 testClassesDirs
和 classpath
具有相同的慣例。除非另行變更,否則預設行為是透過使用 test
組合中的 classpath
和 testClassesDirs
來設定任務,以從預設 test
TestSuite
執行測試。此行為將在 Gradle 9.0 中移除。
雖然此現有預設行為對於在不同環境下執行預設單元測試組合的用例是正確的,但它不支援執行完全不同的測試組合的用例。
如果您想要繼續包含這些測試,請使用下列程式碼,以避免 8.1 中的不建議使用警告,並為 9.0 中的行為變更做好準備。或者,考慮移轉到測試組合。
val test by testing.suites.existing(JvmTestSuite::class)
tasks.named<Test>("myTestTask") {
testClassesDirs = files(test.map { it.sources.output.classesDirs })
classpath = files(test.map { it.sources.runtimeClasspath })
}
tasks.myTestTask {
testClassesDirs = testing.suites.test.sources.output.classesDirs
classpath = testing.suites.test.sources.runtimeClasspath
}
在已填入發布後修改 Gradle 模組元資料
在從元件填入 Maven 或 Ivy 發布之後變更 GMM(例如,變更元件組態變異)現已不建議使用。此功能將在 Gradle 9.0 中移除。
如果呼叫下列方法,可能會急切填入發布
-
Maven
-
Ivy
先前,下列程式碼並未產生警告,但會在已發布的成品之間產生不一致
publishing {
publications {
create<MavenPublication>("maven") {
from(components["java"])
}
create<IvyPublication>("ivy") {
from(components["java"])
}
}
}
// These calls eagerly populate the Maven and Ivy publications
(publishing.publications["maven"] as MavenPublication).artifacts
(publishing.publications["ivy"] as IvyPublication).artifacts
val javaComponent = components["java"] as AdhocComponentWithVariants
javaComponent.withVariantsFromConfiguration(configurations["apiElements"]) { skip() }
javaComponent.withVariantsFromConfiguration(configurations["runtimeElements"]) { skip() }
publishing {
publications {
maven(MavenPublication) {
from components.java
}
ivy(IvyPublication) {
from components.java
}
}
}
// These calls eagerly populate the Maven and Ivy publications
publishing.publications.maven.artifacts
publishing.publications.ivy.artifacts
components.java.withVariantsFromConfiguration(configurations.apiElements) { skip() }
components.java.withVariantsFromConfiguration(configurations.runtimeElements) { skip() }
在此範例中,Maven 和 Ivy 發布將包含專案的主要 JAR 成品,而 GMM 模組檔案 將略過它們。
在 JVM 版本 6 和 7 上執行測試
在低於 8 的 JVM 版本上執行 JVM 測試已不建議使用。在這些版本上進行測試將在 Gradle 9.0 中變成錯誤
套用使用 Gradle < 6.0 發布的 Kotlin DSL 預編譯指令碼
套用使用 Gradle < 6.0 發布的 Kotlin DSL 預編譯指令碼已不建議使用。請使用 Gradle >= 6.0 發布的版本外掛。
套用 kotlin-dsl
搭配 Kotlin Gradle 外掛 < 1.8.0
套用 kotlin-dsl
搭配 Kotlin Gradle 外掛 < 1.8.0 已不建議使用。請讓 Gradle 控制 kotlin-dsl
的版本,方法是從您的建置邏輯中移除任何明確的 kotlin-dsl
版本限制。這將讓 kotlin-dsl
外掛決定要使用哪個版本的 Kotlin Gradle 外掛。如果您明確宣告要為您的建置邏輯使用哪個版本的 Kotlin Gradle 外掛,請將其更新為 >= 1.8.0。
在 Kotlin 指令碼的 plugins {}
區塊中,從相依性版本目錄存取 libraries
或 bundles
在 Kotlin 指令碼的 plugins {}
區塊中,從相依性版本目錄存取 libraries
或 bundles
已不建議使用。請只在 plugins {}
區塊中,從相依性版本目錄使用 versions
或 plugins
。
在沒有 Java 工具鏈的情況下使用 ValidatePlugins
任務
在未套用 Java Toolchains 外掛的情況下使用 ValidatePlugins 類型的任務已過時,且將在 Gradle 9.0 中成為錯誤。
為避免此警告,請將外掛套用至專案
plugins {
id("jvm-toolchains")
}
plugins {
id 'jvm-toolchains'
}
Java Toolchains 外掛會自動套用 Java 函式庫外掛 或其他 JVM 外掛。因此,您可以將其中任何一個套用至專案,即可修正警告。
org.gradle.util
套件的已過時成員現在會回報其過時狀態
這些成員將在 Gradle 9.0 中移除。
-
WrapUtil.toDomainObjectSet(…)
-
GUtil.toCamelCase(…)
-
GUtil.toLowerCase(…)
-
ConfigureUtil
已過時的 JVM 廠商 IBM Semeru
列舉常數 JvmVendorSpec.IBM_SEMERU
現在已過時,且將在 Gradle 9.0 中移除。
請將其替換為等效的 JvmVendorSpec.IBM
,以避免下一個主要版本發布中的警告和潛在錯誤。
在 StartParameter
和 GradleBuild
上設定自訂建置配置
遵循 Gradle 7.1 中 相關過時行為,現在也已過時在相關 StartParameter 和 GradleBuild 屬性中使用。這些屬性將在 Gradle 9.0 中移除。
在 GradleBuild 任務中使用 buildFile 屬性來設定自訂建置檔案已過時。
請改用 dir 屬性來指定巢狀建置的根目錄。或者,考慮使用 GradleBuild 任務的建議替代方案之一,如 避免使用 GradleBuild 任務類型 區段中所建議。
使用 StartParameter 方法 setBuildFile(File) 和 setSettingsFile(File) 以及对应的 getter getBuildFile() 和 getSettingsFile() 设置自定义构建布局已弃用。
请为设置和构建文件使用标准位置
-
构建根目录中的设置文件
-
每个子项目的根目录中的构建文件
已弃用的 org.gradle.cache.cleanup 属性
Gradle 用户目录下 `gradle.properties` 中的 `org.gradle.cache.cleanup` 属性已弃用。请改用 缓存清理 DSL 来禁用或修改清理配置。
由于旧版本 Gradle 可能仍需要 `org.gradle.cache.cleanup` 属性,因此此属性可能仍然存在,只要通过 DSL 配置,就不会打印弃用警告。DSL 值始终优先于 `org.gradle.cache.cleanup` 属性。如果所需的配置是为旧版本 Gradle 禁用清理(使用 `org.gradle.cache.cleanup`),但为 Gradle 8 及以上版本启用具有默认值的清理,则应将清理配置为使用 Cleanup.DEFAULT
if (GradleVersion.current() >= GradleVersion.version('8.0')) {
apply from: "gradle8/cache-settings.gradle"
}
if (GradleVersion.current() >= GradleVersion.version("8.0")) {
apply(from = "gradle8/cache-settings.gradle")
}
beforeSettings { settings ->
settings.caches {
cleanup = Cleanup.DEFAULT
}
}
beforeSettings {
caches {
cleanup.set(Cleanup.DEFAULT)
}
}
已弃用使用相对路径指定 Java 可执行文件
使用相对文件路径指向 Java 可执行文件现已弃用,并将在 Gradle 9 中成为错误。这样做是为了减少对此类相对路径应解析为什么的困惑。
从任务操作调用 Task.getConvention()
、Task.getExtensions()
在执行时从任务操作调用 Task.getConvention()、Task.getExtensions() 现已弃用,并将在 Gradle 9.0 中成为错误。
有关如何将这些用法迁移到配置缓存支持的 API 的详细信息,请参阅 配置缓存章节。
已弃用在未执行任何测试时成功运行测试任务
在未执行任何测试时成功运行 Test
任务现已弃用,并将在 Gradle 9 中成为错误。请注意,当没有测试源时这不是错误,在这种情况下,test
任务只是被跳过。仅当存在测试源但未选择任何测试执行时才出错。此更改是为了避免由于错误配置而导致意外的成功测试运行。
IDE 集成中的更改
不再需要在使用版本目錄的 Kotlin DSL plugins {}
區塊中,對錯誤警示進行因應措施
plugins {}
區塊中,用於外掛別名的版本目錄存取器,不再會在 IntelliJ IDEA 和 Android Studio Kotlin 腳本編輯器中顯示為錯誤。
如果您使用 @Suppress("DSL_SCOPE_VIOLATION")
注解作為因應措施,現在可以移除它了。
如果您使用 IntelliJ IDEA 外掛 Gradle Libs Error Suppressor,現在可以將它解除安裝。
升級 Gradle 至 8.1 後,您需要清除 IDE 快取並重新啟動。