此章節提供您將舊版 Gradle 4.x 建置移轉到 Gradle 5.0 所需的資訊。在多數情況下，您需要套用從您要升級的版本之後的所有版本所做的變更。例如，如果您要從 Gradle 4.3 升級到 5.0，您也需要套用自 4.4、4.5 等版本到 5.0 為止所做的變更。

如果您使用 Gradle for Android，您需要移轉到 Android Gradle 外掛程式和 Android Studio 的 3.3 或更高版本。

所有使用者

  1. 如果您尚未使用最新的 4.10.x 版本，請閱讀下方的章節，以取得將專案升級到最新 4.10.x 版本的說明。我們建議升級到最新的 4.10.x 版本，以在移轉到 5.0 之前取得最有用的警告和不建議使用資訊。請避免同時升級 Gradle 和移轉到 Kotlin DSL，以利於在發生潛在問題時輕鬆進行疑難排解。

  2. 請嘗試執行 `gradle help --scan` 並查看所產生建置掃描的不建議使用檢視。如果沒有警告，則「不建議使用」標籤不會出現。

    Deprecations View of a Gradle Build Scan

    這樣您就可以看到任何適用於您建置的不建議使用警告。如果您嘗試直接升級到 Gradle 5.x，則它會產生（可能較不明顯的）錯誤。

    或者，您可以執行 `gradle help --warning-mode=all` 以在主控台中查看不建議使用資訊，不過它可能不會報告太多詳細資訊。

  3. 更新您的外掛程式。

    有些外掛程式會因這個新版本的 Gradle 而中斷，例如因為它們使用已移除或已變更的內部 API。前一步驟會在外掛程式嘗試使用 API 的不建議使用部分時發出不建議使用警告，以協助您找出潛在問題。

    特別是，您需要使用至少 2.x 版本的Shadow 外掛程式。

  4. 執行 `gradle wrapper --gradle-version 5.0` 以將專案更新至 5.0

  5. 如果您尚未執行，請移轉至 Java 8 或更高版本。Gradle 4.x 需要 Java 7，而 Gradle 5 需要 Java 8 才能執行。

  6. 請閱讀從 4.10 升級章節，並進行必要的變更。

  7. 請嘗試執行專案，並使用疑難排解指南偵錯任何錯誤。

此外，Gradle 已新增多項重大且改良的功能，您應考慮在您的建置中使用這些功能

其他可能中斷您的建置的重大變更包括

從 4.10 及更早版本升級

如果您尚未使用版本 4.10，請跳至套用您目前 Gradle 版本的部分，並持續升級，直到您到達此處。然後，在從 Gradle 4.10 移轉至 5.0 時，套用這些變更。

其他變更

  • enableFeaturePreview('IMPROVED_POM_SUPPORT') 和 enableFeaturePreview('STABLE_PUBLISHING') 旗標不再必要。這些功能現在預設啟用。

  • Gradle 現在為 Java 9 及以上版本綑綁 JAXB。如果您已設定，您可以從 org.gradle.jvmargs 中移除 --add-modules java.xml.bind 選項。

潛在中斷變更

此部分的變更可能會中斷您的建置，但絕大多數變更已棄用一段時間，而且很少建置會受到大量變更的影響。我們強烈建議您先升級至 Gradle 4.10，以取得一份報告，了解哪些棄用會影響您的建置。

下列中斷變更並非來自棄用，而是行為變更的結果

以下重大變更會在 Gradle 4.10 中顯示為不建議使用的警告

一般

  • << 不再適用於任務定義。換句話說，您無法使用語法 task myTask << { …​ }。

    請改用 Task.doLast() 方法，如下所示

    task myTask {
    doLast {
        ...
    }
}

  • 您不能再在網域物件名稱（例如專案和任務名稱）中使用下列任何字元：<space> / \ : < > " ? * | 。您也不應將 . 用作開頭或結尾字元。

執行 Gradle 和組建環境

  • 如前所述，Gradle 不再能在 Java 7 上執行。不過，您仍可以使用 分支編譯和測試 來為 Java 6 以上版本組建和測試軟體。

  • 已移除 -Dtest.single 命令列選項，請改用 測試篩選。

  • 已移除 -Dtest.debug 命令列選項，請改用 --debug-jvm 選項。

  • 已移除 -u/--no-search-upward 命令列選項，請務必讓所有組建都有 settings.gradle 檔案。

  • 已移除 --recompile-scripts 命令列選項。

  • 除非嵌套組建有 settings.gradle 檔案，否則您不能再讓 Gradle 組建嵌套在另一個 Gradle 組建的子目錄中。

  • 已移除 DirectoryBuildCache.setTargetSizeInMB(long) 方法，請改用 DirectoryBuildCache.removeUnusedEntriesAfterDays。

  • org.gradle.readLoggingConfigFile 系統屬性不再執行任何動作，請更新受影響的測試，以配合您的 java.util.logging 設定。

使用檔案

  • 您無法再使用 as 關鍵字或 asType() 方法將 FileCollection 物件轉換為其他類型。

  • 您無法再將 null 傳遞為 CopySpec.from(Object, Action) 的組態動作。

  • 為了與 Kotlin DSL 更相容，CopySpec.duplicatesStrategy 不再為可為空。屬性設定器不再接受 null 作為將屬性重設回其預設值的方式。請改用 DuplicatesStrategy.INHERIT。

  • 已移除 FileCollection.stopExecutionIfEmpty() 方法 — 請改用 FileCollection 任務屬性上的 @SkipWhenEmpty 註解。

  • 已移除 FileCollection.add() 方法 — 請使用 Project.files() 和 Project.fileTree() 來建立可組態的檔案集合/檔案樹，並透過 ConfigurableFileCollection.from() 將其新增至其中。

  • 已移除 SimpleFileCollection — 請改用 Project.files(Object…​)。

  • 不要讓您自己的類別延伸 AbstractFileCollection — 請改用 Project.files() 方法。此問題可能會表現為缺少 getBuildDependencies() 方法。

Java 建置
工作和屬性

  • 與 延遲屬性 相關的下列舊式類別和方法已被移除，請使用 ObjectFactory.property() 建立 Property 執行個體

    • PropertyState

    • DirectoryVar

    • RegularFileVar

    • ProjectLayout.newDirectoryVar()

    • ProjectLayout.newFileVar()

    • Project.property(Class)

    • Script.property(Class)

    • ProviderFactory.property(Class)

  • 使用 工作設定迴避 API 設定和註冊的工作在從設定動作呼叫的其他方法方面有更多限制。

  • 內部 @Option 和 @OptionValues 註解（套件 org.gradle.api.internal.tasks.options）已移除。請改用公開的 @Option 和 @OptionValues 註解。

  • Task.deleteAllActions() 方法已移除，沒有替換。

  • Task.dependsOnTaskDidWork() 方法已移除，請改用 宣告的輸入和輸出。

  • TaskInternal 的下列屬性和方法已移除，請使用工作相依性、工作規則、可重複使用的公用程式方法或 工作人員 API 來取代直接執行工作。

    • execute()

    • 執行器

    • getValidators()

    • addValidator()

  • TaskInputs.file(Object) 方法不再能使用會解析為單一常規檔案以外的引數呼叫。

  • TaskInputs.dir(Object) 方法不再能使用會解析為單一目錄以外的引數呼叫。

  • 您不再能透過 TaskInputs 和 TaskOutputs 註冊無效的輸入和輸出。

  • TaskDestroyables.file() 和 TaskDestroyables.files() 方法已移除，請改用 TaskDestroyables.register()。

  • SimpleWorkResult 已移除，請改用 WorkResult.didWork。

  • 覆寫內建任務 已於 4.8 版中標示為不建議使用，現在會產生錯誤。

    嘗試取代內建任務會產生類似下列訊息的錯誤

    > Cannot add task 'wrapper' as a task with that name already exists.
Scala 和 Play

  • Play 2.2 已不再受支援，請升級您使用的 Play 版本。

  • ScalaDocOptions.styleSheet 屬性已移除，Scala 2.11.8 和更新版本的 Scaladoc Ant 任務不再支援此屬性。

Kotlin DSL

  • 人工製品組態存取器現在的型別為 NamedDomainObjectProvider<Configuration>，而非 Configuration

  • PluginAware.apply<T>(to) 已重新命名為 PluginAware.applyTo<T>(target)。

這兩個變更都可能導致指令碼編譯錯誤。請參閱 Gradle Kotlin DSL 發行說明，以取得更多資訊，以及如何修正因上述變更而損毀的建置。

其他

  • ConfigurableReport.setDestination(Object) 方法已移除，請改用 ConfigurableReport.setDestination(File)。

  • Signature.setFile(File) 方法已移除，Gradle 不支援變更已產生簽章的輸出檔案。

  • 唯讀 Signature.toSignArtifact 屬性已移除，它不應成為公開 API 的一部分。

  • @DeferredConfigurable 註解已移除。

  • isDeferredConfigurable() 方法已從 ExtensionSchema 中移除。

  • IdeaPlugin.performPostEvaluationActions() 和 EclipsePlugin.performPostEvaluationActions() 已移除。

  • The `BroadcastingCollectionEventRegister.getAddAction() 方法已移除，且無替代方法。

  • 內部 org.gradle.util 套件不再預設匯入。

    理想上您不應使用此套件中的類別，但作為快速修正，您可以為這些類別在您的建置腳本中加入明確的匯入。

  • gradlePluginPortal() 儲存庫 不再預設尋找沒有 POM 的 JAR。

  • Tooling API 無法再連線到 Gradle 版本低於 Gradle 2.6 的建置。TestKit 執行建置時也適用相同情況。

  • Gradle 5.0 需要最低 Tooling API 3.0 客户端版本。較舊的客户端函式庫無法再使用 Gradle 5.0 執行建置。

  • IdeaModule Tooling API 模型元素包含用於擷取資源和測試資源的方法，因此這些元素已從 IdeaModule.getSourceDirs() 和 IdeaModule.getTestSourceDirs() 的結果中移除。

  • 在之前的 Gradle 版本中，SourceTask 中的 source 欄位可從子類別存取。現在不再適用，因為 source 欄位現已宣告為 private。

  • 在 Worker API 中，無法再設定 worker 的工作目錄。

  • 與 相依關係和版本約束 相關的行為變更可能會影響少數使用者。

  • DefaultTask 上的 屬性工廠方法 已有數項變更，可能會影響自訂任務的建立。

從 4.9 及更早版本升級

如果您尚未使用 4.9 版本，請跳到適用於您目前 Gradle 版本的部分，並逐一進行升級，直到此處。然後，在升級到 Gradle 4.10 時套用這些變更。

已淘汰的類別、方法和屬性

請遵循 API 連結，以了解如何處理這些淘汰項目（如果此處未提供其他資訊）

潛在的重大變更

從 4.8 及更早版本升級

潛在的重大變更

從 4.7 及更早版本升級

潛在的重大變更

  • 如果找不到指定的初始化指令碼，建置現在會失敗。

  • TaskContainer.remove() 現在實際上會移除指定的任務 — 有些外掛程式可能意外依賴舊行為。

  • Gradle 現在支援 Maven POM 排除中的隱含萬用字元.

  • Kotlin DSL 現在尊重 JSR-305 套件註解。

    這將導致根據 JSR-305 註解的一些類型被視為可為空，而之前被視為不可為空。這可能會導致建置指令碼中的編譯錯誤。有關詳細資訊，請參閱 相關的 Kotlin DSL 發行說明。

  • 錯誤訊息現在會導向標準錯誤，而不是標準輸出，除非主控台同時附加到標準輸出和標準錯誤。這可能會影響擷取建置純文字主控台輸出的工具。如果您從較早版本的 Gradle 升級，請忽略此變更。

不建議使用的項目

在此版本之前，建置允許取代內建任務。 此功能已不建議使用。

不應取代的內建任務完整清單：wrapper、init、help、tasks、projects、buildEnvironment、components、dependencies、dependencyInsight、dependentComponents、model、properties。

從 4.6 及更早版本升級

潛在中斷變更

  • 根據慣例，Gradle 現在會在根專案的 config/checkstyle 目錄中尋找 Checkstyle 組態檔案。

    子專案中的 Checkstyle 組態檔案（舊的慣例位置）將會被忽略，除非您透過 checkstyle.configDir 或 checkstyle.config 明確組態其路徑。

  • Gradle 的 純文字主控台輸出 結構已變更，這可能會中斷擷取該輸出的工具。

  • 與編譯、連結和安裝相關的許多原生任務的 API 已以中斷方式變更。

  • [Kotlin DSL] 用於存取 Gradle 建置屬性的委派屬性（例如定義在 gradle.properties 中）現在必須明確指定型別。

  • [Kotlin DSL] 現在在巢狀範圍內宣告 plugins {} 區塊會擲回例外。

  • [Kotlin DSL] 現在只允許一個 pluginManagement {} 區塊。

  • org.gradle.api.artifacts.cache.* 介面提供的快取控制 DSL 已不再可用。

  • getEnabledDirectoryReportDestinations()、getEnabledFileReportDestinations() 和 getEnabledReportNames() 已全部從 org.gradle.api.reporting.ReportContainer 中移除。

  • StartParameter.projectProperties 和 StartParameter.systemPropertiesArgs 現在會傳回不可變的對應。

從 4.5 及更早版本升級

已棄用

  • 您不應將註解處理器放在編譯類別路徑上，或使用 -processorpath 編譯器參數宣告它們。

    它們應該新增到 annotationProcessor 組態中。如果您不想要任何處理，但您的編譯類別路徑意外包含處理器（例如，作為您依賴的函式庫的一部分），請使用 -proc:none 編譯器參數來忽略它。

  • 使用 CommandLineArgumentProvider 取代 CompilerArgumentProvider。

潛在的重大變更

  • Java 外掛現在會為每個來源組新增一個 sourceSetAnnotationProcessor 組態，如果其中任何一個與您現有的組態相符，可能會中斷。我們建議您移除衝突的組態宣告。

  • StartParameter.taskOutputCacheEnabled 屬性已被 StartParameter.setBuildCacheEnabled(boolean) 取代。

  • Visual Studio 整合現在只會 為建置中的所有元件組態單一解決方案。

  • Gradle 已將 HttpClient 4.4.1 取代為版本 4.5.5。

  • Gradle 現在會綑綁 kotlin-stdlib-jdk8 製成品，而不是 kotlin-stdlib-jre8。這可能會影響您的建置。請參閱 Kotlin 文件 以取得更多詳細資訊。

從 4.4 及更早版本升級

  • 請確定您有一個 settings.gradle 檔案：它避免效能損失，並允許您設定根專案的名稱。

  • Gradle 現在會忽略包含建置（複合建置）的建置快取組態，並改為對所有建置使用根建置的組態。

潛在的重大變更

  • 已移除兩個重載的 ValidateTaskProperties.setOutputFile() 方法。當從建置指令碼存取任務時，它們會以自動產生的設定器取代，但外掛程式和其他建置指令碼外部的程式碼並非如此。

  • Maven 發佈外掛程式現在會產生更完整的 maven-metadata.xml 檔案，包括維護 <snapshotVersion> 元素清單。某些較舊版本的 Maven 可能無法使用這些元資料。

  • HttpBuildCache 不再遵循重新導向.

  • 已移除 Depend 任務類型。

  • Project.file(Object) 不再對不分大小寫檔案系統上的檔案路徑正規化大小寫。它現在會在這種情況下忽略大小寫，且不觸及檔案系統。

  • ListProperty 不再延伸 Property。

從 4.3 及更早版本升級

潛在中斷變更

從 4.2 及更早版本升級

其他已棄用的功能

潛在的重大變更

  • DefaultTask.newOutputDirectory() 現在會傳回 DirectoryProperty，而不是 DirectoryVar。

  • DefaultTask.newOutputFile() 現在會傳回 RegularFileProperty，而不是 RegularFileVar。

  • DefaultTask.newInputFile() 現在會傳回 RegularFileProperty，而不是 RegularFileVar。

  • ProjectLayout.buildDirectory 現在會傳回 DirectoryProperty，而不是 DirectoryVar。

  • AbstractNativeCompileTask.compilerArgs 現在的類型為 ListProperty<String>，而不是 List<String>。

  • AbstractNativeCompileTask.objectFileDir 現在的類型為 DirectoryProperty，而不是 File。

  • AbstractLinkTask.linkerArgs 現在的類型為 ListProperty<String>，而不是 List<String>。

  • TaskDestroyables.getFiles() 不再是公開 API 的一部分。

  • 相依項目的重疊版本範圍現在會導致 Gradle 選擇一個滿足所有宣告範圍的版本。

    例如，如果發現對 some-module 的依賴項版本範圍為 [3,6]，且也傳遞依賴於範圍 [4,8]，則 Gradle 現在會選擇版本 6，而不是 8。先前的行為是選擇 8。

  • 標記為 @OutputFiles 或 @OutputDirectories 的 Iterable 屬性的元素順序現在很重要。如果順序變更，則該屬性不再被視為最新。

    建議使用帶有 @OutputFile/@OutputDirectory 註解的個別屬性，或使用帶有 @OutputFiles/@OutputDirectories 的 Map 屬性。

  • 當有另一個可以檢查的儲存庫時，Gradle 將不再忽略儲存庫的依賴項解析錯誤。相反地，依賴項解析將會失敗。這會導致解析結果具有更確定的行為。

從 4.1 及更早版本升級

潛在中斷變更

  • 已移除 TaskFilePropertyBuilder 和 TaskOutputFilePropertyBuilder 上的 withPathSensitivity() 方法。

  • 已將捆綁的 bndlib 從 3.2.0 升級至 3.4.0。

  • FindBugs 外掛程式不再從其分析中呈現進度資訊。如果您以任何方式依賴該輸出，則可以使用 FindBugs.showProgress 來啟用它。

從 4.0 升級

  • 考慮使用新的 Worker API，以讓您的建置中的工作單元能夠並行執行。

已棄用的類別、方法和屬性

請遵循 API 連結，以了解如何處理這些淘汰項目（如果此處未提供其他資訊）

潛在中斷變更

  • 對 Java 專案有 專案依賴項 的非 Java 專案現在預設會使用 runtimeElements 組態，而不是 default 組態。

    若要覆寫此行為，您可以在專案依賴項中明確宣告要使用的組態。例如：project(path: ':myJavaProject', configuration: 'default')。

  • 預設 Zinc 編譯器已從 0.3.13 升級至 0.3.15。

  • [Kotlin DSL] 基本套件已從 org.gradle.script.lang.kotlin 重新命名為 org.gradle.kotlin.dsl。

詳細變更

[5.0] 預設記憶體設定已變更

命令列用戶端現在以 64MB 的堆積區啟動，而非 1GB。這可能會影響在用戶端 VM 內使用 --no-daemon 模式直接執行的建置。我們不建議使用 --no-daemon，但如果您必須使用它，您可以使用 GRADLE_OPTS 環境變數來增加可用記憶體。

Gradle 守護程式現在以 512MB 的堆積區啟動，而非 1GB。大型專案可能必須使用 org.gradle.jvmargs 屬性來增加此設定。

所有工作執行緒，包括編譯器和測試執行器，現在都以 512MB 的堆積區啟動。之前的預設值是實體記憶體的 1/4。大型專案可能必須針對相關任務增加此設定，例如 JavaCompile 或 Test。

[5.0] 程式碼品質外掛的新預設版本

下列程式碼品質外掛的預設工具版本已更新

  • Checkstyle 外掛 現在預設使用 8.12，而非 6.19。

  • CodeNarc 外掛 現在預設使用 1.2.1，而非 1.1。

  • JaCoCo 外掛 現在預設使用 0.8.2，而非 0.8.1。

  • PMD 外掛 現在預設使用 6.8.0，而非 5.6.1。

    此外，預設規則集已從現已棄用的 java-basic 變更為 category/java/errorprone.xml。

    不過，我們建議明確設定規則集。

[5.0] 函式庫升級

Gradle 使用的數個函式庫已升級

  • Groovy 已從 2.4.15 升級至 2.5.4。

  • Ant 已從 1.9.11 升級至 1.9.13。

  • 用於存取 S3 支援的 Maven/Ivy 儲存庫的 AWS SDK 已從 1.11.267 升級至 1.11.407。

  • OSGi 外掛使用的 BND 函式庫已從 3.4.0 升級至 4.0.0。

  • 用於存取 Google Cloud Storage 支援的 Maven/Ivy 儲存庫的 Google Cloud Storage JSON API Client 函式庫已從 v1-rev116-1.23.0 升級至 v1-rev136-1.25.0。

  • Ivy 已從 2.2.0 升級至 2.3.0。

  • Test 任務使用的 JUnit Platform 函式庫已從 1.0.3 升級至 1.3.1。

  • 用於存取 Maven 儲存庫的 Maven Wagon 函式庫已從 2.4 升級至 3.0.0。

  • SLF4J 已從 1.7.16 升級至 1.7.25。

[5.0] 改善對相依性和版本限制的支持

透過 Gradle 4.x 發行串流，新的 @Incubating 功能已新增至相依性解析引擎。這些功能包括精密的版本限制 (prefer、strictly、reject)、相依性限制和 platform 相依性。

如果您一直使用 IMPROVED_POM_SUPPORT 功能預覽，試用限制或偏好、拒絕和其他特定版本指示，請務必仔細查看您的相依性解析結果。

[5.0] BOM 匯入

Gradle 現在提供支援，用於匯入物料清單 (BOM) 檔案，這些檔案實際上是使用 <dependencyManagement> 區段來控制直接和傳遞相依性的版本之 POM 檔案。您只需將 POM 宣告為 platform 相依性即可。

下列範例從宣告的 Spring Boot BOM 選取 gson 和 dom4j 相依性的版本

dependencies {
    // import a BOM
    implementation platform('org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE')

    // define dependencies without versions
    implementation 'com.google.code.gson:gson'
    implementation 'dom4j:dom4j'
}

[5.0] 使用 POM 時，編譯和執行時期相依性的區分

自 Gradle 1.0 以來，執行時期範圍的相依性已包含在 Java 編譯類別路徑中，這有一些缺點

  • 編譯類別路徑比它需要的還要大，會減慢編譯速度。

  • 編譯類別路徑包含不會影響編譯的執行時期範圍檔案，導致在這些檔案變更時不必要地重新編譯。

有了這個新行為，Java 和 Java 函式庫外掛程式都尊重 編譯和執行時期範圍的區分。這表示編譯類別路徑只包含編譯範圍的相依性，而執行時期類別路徑也會新增執行時期範圍的相依性。如果您使用 Gradle 開發和發布 Java 函式庫，這會特別有用，其中 api 和 implementation 相依性之間的區分會反映在發布的範圍中。

[5.0] 變更 DefaultTask 上的屬性工廠方法

DefaultTask 上的屬性工廠方法現在為 final

屬性工廠方法，例如 newInputFile()，旨在從延伸 DefaultTask 的類型的建構函式中呼叫。這些方法現在為 final，以避免子類別覆寫這些方法並使用未初始化的狀態。

輸入和輸出不會自動註冊

這些方法傳回的 Property 實例不再自動註冊為任務的輸入或輸出。Property 實例需要以一般方式宣告為輸入或輸出，例如附加註解，例如 @OutputFile 或使用執行時期 API 註冊該屬性。

例如，您先前可以使用下列語法，並將兩個 outputFile 實例註冊為已宣告的輸出

build.gradle
class MyTask extends DefaultTask {
    // note: no annotation here
    final RegularFileProperty outputFile = newOutputFile()
}

task myOtherTask {
    def outputFile = newOutputFile()
    doLast { ... }
}
build.gradle.kts
open class MyTask : DefaultTask() {
    // note: no annotation here
    val outputFile: RegularFileProperty = newOutputFile()
}

task("myOtherTask") {
    val outputFile = newOutputFile()
    doLast { ... }
}

現在您必須明確註冊 outputFile，如下所示

build.gradle
class MyTask extends DefaultTask {
    @OutputFile // property needs an annotation
    final RegularFileProperty outputFile = project.objects.fileProperty()
}

task myOtherTask {
    def outputFile = project.objects.fileProperty()
    outputs.file(outputFile) // or to be registered using the runtime API
    doLast { ... }
}
build.gradle.kts
open class MyTask : DefaultTask() {
    @OutputFile // property needs an annotation
    val outputFile: RegularFileProperty = project.objects.fileProperty()
}

task("myOtherTask") {
    val outputFile = project.objects.fileProperty()
    outputs.file(outputFile) // or to be registered using the runtime API
    doLast { ... }
}

[5.0] Gradle 現在會將 JAXB 綑綁到 Java 9 以上版本

為了使用 S3 支援的成品儲存庫，您先前必須在 Java 9 以上版本執行時，將 --add-modules java.xml.bind 加入 org.gradle.jvmargs。

由於 Java 11 不再包含 java.xml.bind 模組，因此 Gradle 現在會將 JAXB 2.3.1 (com.sun.xml.bind:jaxb-impl) 綑綁在一起，並在 Java 9 以上版本使用它。

請移除 org.gradle.jvmargs 中的 --add-modules java.xml.bind 選項（如果已設定）。

[5.0] gradlePluginPortal() 儲存庫預設不再尋找沒有 POM 的 JAR

有了這個新行為，如果在 gradlePluginPortal() 儲存庫中找到的 plugin 或 plugin 的傳遞相依項沒有 Maven POM，則無法解析。

發佈到 Maven 儲存庫而沒有 POM 的成品應該修正。如果您遇到此類成品，請要求 plugin 或程式庫作者發佈具有適當元資料的新版本。

如果您遇到有問題的 plugin，您可以透過重新啟用 JAR 作為 gradlePluginPortal() 儲存庫的元資料來源來解決問題

settings.gradle
pluginManagement {
    repositories {
        gradlePluginPortal().tap {
            metadataSources {
                mavenPom()
                artifact()
            }
        }
    }
}
settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal().apply {
            (this as MavenArtifactRepository).metadataSources {
                mavenPom()
                artifact()
            }
        }
    }
}

Java Library Distribution Plugin 使用 Java Library Plugin

現在，Java Library Distribution Plugin 是以 Java Library Plugin 為基礎，而非 Java Plugin。

此外，plugin 建立的預設發行版將包含 runtimeClasspath 設定的所有成品，而不是已棄用的 runtime 設定。

設定避免 API 禁止常見的設定錯誤

Gradle 4.9 中推出的 設定避免 API 讓您可以避免建立和設定從未使用的任務。

使用現有的 API，此範例會新增兩個任務（foo 和 bar）

build.gradle
tasks.create("foo") {
    tasks.create("bar")
}
build.gradle.kts
tasks.create("foo") {
    tasks.create("bar")
}

將其轉換為使用新 API 時，會發生令人驚訝的事情：bar 不存在。新 API 僅在必要時執行設定動作，因此任務 bar 的 register() 僅在設定 foo 時執行。

build.gradle
tasks.register("foo") {
    tasks.register("bar") // WRONG
}
build.gradle.kts
tasks.register("foo") {
    tasks.register("bar") // WRONG
}

為了避免這種情況，Gradle 現在會偵測這一點，並在使用新 API 時防止修改基礎容器（透過 create() 或 register()）。

[5.0] Worker API：無法再設定 worker 的工作目錄

由於 JDK 11 不再支援變更執行中程序的工作目錄，因此現在禁止透過 fork 選項設定 worker 的工作目錄。

所有 worker 現在使用相同的工作目錄以啟用重複使用。

請改為將檔案和目錄傳遞為引數。

[4.10] 發佈至 AWS S3 需要新的權限

S3 儲存庫傳輸協定允許 Gradle 將成品發佈至 AWS S3 儲存區。從此版本開始，上傳至 S3 儲存區的每個成品都將配備 bucket-owner-full-control 罐頭 ACL。請確定用於發佈成品的 AWS 帳戶具有 s3:PutObjectAcl 和 s3:PutObjectVersionAcl 權限，否則上傳將會失敗。

{
    "Version":"2012-10-17",
    "Statement":[
        // ...
        {
            "Effect":"Allow",
            "Action":[
                "s3:PutObject", // necessary for uploading objects
                "s3:PutObjectAcl", // required starting with this release
                "s3:PutObjectVersionAcl" // if S3 bucket versioning is enabled
            ],
            "Resource":"arn:aws:s3:::myCompanyBucket/*"
        }
    ]
}

請參閱 AWS S3 交叉帳戶存取 以取得更多資訊。

[4.9] 考慮嘗試使用延遲 API 進行任務建立和組態

Gradle 4.9 引進了一種新的方式來建立和組態任務，其運作方式為延遲。當您對組態成本較高的任務使用此方法，或當您有非常多任務時，如果這些任務未執行，您的建置組態時間可能會大幅縮短。

您可以在 避免任務組態 章節中進一步瞭解延遲建立任務。您也可以在 這篇部落格文章 中閱讀此新功能的背景資訊。

[4.8] 切換至 Maven Publish 和 Ivy Publish 外掛程式

由於發布外掛現已穩定，我們建議您從標準 Java 專案的舊版發布機制（即基於 Java 外掛 的專案）進行移轉。這包括使用下列任一項目的專案：Java 函式庫外掛、應用程式外掛 或 War 外掛。

若要使用新方法，只需將任何 upload<Conf> 設定檔取代為 publishing {} 區塊。請參閱 發布概觀章節 以取得更多資訊。

[4.8] 為發布外掛使用延遲設定

在 Gradle 4.8 之前，publishing {} 區塊會被隱含地視為在專案評估後執行區塊內的所有邏輯。這很令人困惑，因為這是唯一會以這種方式運作的區塊。作為 Gradle 4.8 穩定性改善工作的一部分，我們將棄用此行為，並要求所有使用者移轉其建置。

可以透過將下列內容新增到設定檔中，來切換新的穩定行為

settings.gradle
enableFeaturePreview('STABLE_PUBLISHING')
settings.gradle.kts
enableFeaturePreview("STABLE_PUBLISHING")

我們建議使用本機存放庫進行測試執行，以查看所有成品是否仍具有預期的座標。在大部分情況下，所有內容都應如前一樣運作，而且您已完成。但是，您的發布區塊可能依賴於隱含的延遲設定，特別是如果它依賴於建置設定階段中可能會變動的值。

例如，在新的行為下，下列邏輯假設 jar.archiveBaseName 在設定 artifactId 之後不會變動

build.gradle
subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                artifactId = jar.archiveBaseName
            }
        }
    }
}
build.gradle.kts
subprojects {
    publishing {
        publications {
            named<MavenPublication>("mavenJava") {
                from(components["java"])
                artifactId = tasks.jar.get().archiveBaseName.get()
            }
        }
    }
}

如果該假設不正確或未來可能不正確，則必須在 afterEvaluate {} 區塊中設定 artifactId，如下所示

build.gradle
subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                afterEvaluate {
                    artifactId = jar.archiveBaseName
                }
            }
        }
    }
}
build.gradle.kts
subprojects {
    publishing {
        publications {
            named<MavenPublication>("mavenJava") {
                from(components["java"])
                afterEvaluate {
                    artifactId = tasks.jar.get().archiveBbaseName.get()
                }
            }
        }
    }
}

[4.8] 設定現有的 wrapper 和 init 工作

您不應再定義自己的 wrapper 和 init 工作。請改為設定現有的工作，例如將此

build.gradle
task wrapper(type: Wrapper) {
    ...
}
build.gradle.kts
task<Wrapper>("wrapper") {
    ...
}

轉換為此

build.gradle
wrapper {
    ...
}
build.gradle.kts
tasks.wrapper {
    ...
}

[4.8] Gradle 現在會遵循 Maven POM 排除中的隱含萬用字元

如果 Maven POM 中的排除項缺少 groupId 或 artifactId，Gradle 過去會忽略排除項。現在，遺失的元素會被視為隱含萬用字元，例如 <groupId>*</groupId>，這表示您的一些相依項現在可能會被排除，而過去不會。

您需要明確宣告您需要的任何遺失相依項。

[4.7] 變更 Gradle 純文字主控台輸出的結構

純文字主控台模式現在會以與豐富主控台一致的方式格式化輸出，這表示輸出格式已變更。例如

  • 特定工作所產生的輸出現在會群組在一起，即使其他工作與其平行執行也是如此。

  • 工作執行標頭會加上「> 工作」前綴列印。

  • 在建置執行期間產生的所有輸出都會寫入標準輸出檔案處理常式。這包括寫入 System.err 的訊息，除非您將標準錯誤重新導向到檔案或任何其他非主控台目的地。

這可能會中斷從純文字主控台輸出中擷取詳細資料的工具。

[4.6] 變更與編譯、連結和安裝相關的原生工作 API

許多與編譯、連結和安裝原生程式庫和應用程式的相關工作已轉換為提供者 API，以便支援 延遲組態。此轉換已對工作的 API 進行了一些重大變更，以便符合提供者 API 的慣例。

已變更下列工作

AbstractLinkTask 及其子類別

  • getDestinationDir() 已被 getDestinationDirectory() 取代。

  • getBinaryFile()、getOutputFile() 已被 getLinkedFile() 取代。

  • 已移除 setOutputFile(File)。請改用 Property.set()。

  • 已移除 setOutputFile(Provider)。請改用 Property.set()。

  • 已變更 getTargetPlatform() 以傳回 Property。

  • 已移除 setTargetPlatform(NativePlatform)。請改用 Property.set()。

  • 已變更 getToolChain() 以傳回 Property。

  • 已移除 setToolChain(NativeToolChain)。請改用 Property.set()。

CreateStaticLibrary

  • 已變更 getOutputFile() 以傳回 Property。

  • 已移除 setOutputFile(File)。請改用 Property.set()。

  • 已移除 setOutputFile(Provider)。請改用 Property.set()。

  • 已變更 getTargetPlatform() 以傳回 Property。

  • 已移除 setTargetPlatform(NativePlatform)。請改用 Property.set()。

  • 已變更 getToolChain() 以傳回 Property。

  • 已移除 setToolChain(NativeToolChain)。請改用 Property.set()。

  • 已變更 getStaticLibArgs() 以傳回 ListProperty。

  • setStaticLibArgs(List) 已移除。請改用 ListProperty.set()。

InstallExecutable

  • getSourceFile() 已被 getExecutableFile() 取代。

  • getPlatform() 已被 getTargetPlatform() 取代。

  • 已移除 setTargetPlatform(NativePlatform)。請改用 Property.set()。

  • 已變更 getToolChain() 以傳回 Property。

  • 已移除 setToolChain(NativeToolChain)。請改用 Property.set()。

以下也已看到類似的變更

[4.6] Visual Studio 整合僅支援單一解決方案檔案，供建置的所有元件使用

VisualStudioExtension 不再有 solutions 屬性。相反地，您透過根專案中的 VisualStudioRootExtension 設定單一解決方案，如下所示

build.gradle
model {
    visualStudio {
        solution {
            solutionFile.location = "vs/${name}.sln"
        }
    }
}

此外，不再有個別任務來產生每個元件的解決方案檔案，而是單一的 visualStudio 任務，產生包含建置中所有元件的解決方案檔案。

[4.5] HttpBuildCache 不再遵循重新導向

當透過 HttpBuildCache 連線到 HTTP 建置快取後端時，Gradle 不再遵循重新導向，而是將它們視為錯誤。從建置快取後端取得重新導向通常是設定錯誤 (例如使用「http」URL 而不是「https」)，而且會對效能造成負面影響。

[4.4] 第三方相依性升級

此版本包含多項第三方相依性的升級

  • jackson: 2.6.6 → 2.8.9

  • plexus-utils: 2.0.6 → 2.1

  • xercesImpl: 2.9.1 → 2.11.0

  • bsh: 2.0b4 → 2.0b6

  • bouncycastle: 1.57 → 1.58

此修正程式修正下列安全性問題

Gradle 沒有公開這些第三方相依性的公開 API，但自訂 Gradle 的人會想要知道。