Gradle 發行說明

升級說明

透過更新專案中的 wrapper，將您的建置切換為使用 Gradle 8.13

./gradlew wrapper --gradle-version=8.13 && ./gradlew wrapper

請參閱 Gradle 8.x 升級指南，以了解升級到 Gradle 8.13 時的棄用、重大變更和其他注意事項。

關於 Java、Groovy、Kotlin 和 Android 相容性，請參閱完整相容性說明。

新功能和可用性改進

工具鏈支援

Gradle 的 工具鏈支援 允許配置和選擇建置專案（編譯程式碼、執行測試等）以及執行 Gradle 本身所需的 JDK 版本。

Daemon 工具鏈自動配置

自 Gradle 8.8 起，使用者可以透過配置 Daemon JVM 標準，指定與執行 Gradle 不同的 JVM 來建置專案。
Gradle 首先嘗試從已安裝的版本中找到相容的 Java 工具鏈 — 此過程稱為 Daemon JVM 自動偵測。

隨著 Daemon JVM 自動配置 的引入，當本地找不到相符的 Java 工具鏈時，Gradle 現在也可以下載相符的 Java 工具鏈。

執行 updateDaemonJvm 任務會產生 gradle/gradle-daemon-jvm.properties 檔案，現在其中包含所需 JDK 的下載 URL

toolchainUrl.LINUX.AARCH64=https\://server.com/jdk
toolchainUrl.LINUX.X86_64=https\://server.com/jdk
...
toolchainVendor=adoptium
toolchainVersion=17

如果沒有已安裝的 JDK 符合指定的版本或供應商，Gradle 會自動下載所需的版本

IntelliJ IDEA 支援從 2025.1 EAP 或更高版本開始提供，並在「設定」選單中包含可配置的值

若要啟用自動配置，需要最新版本的 foojay 外掛程式（或自訂實作）

plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}

套用外掛程式後，執行 updateDaemonJvm 任務

./gradlew updateDaemonJvm --jvm-version=17 --jvm-vendor=adoptium

會使用 JDK 下載資訊填入 gradle/gradle-daemon-jvm.properties

toolchainUrl.LINUX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/ff8d269e2495c538cfa04b4b52d22286/redirect
toolchainUrl.LINUX.X86_64=https\://api.foojay.io/disco/v3.0/ids/4dfe7aab2abf71db71537e9dca36c154/redirect
...
toolchainVendor=adoptium
toolchainVersion=17

已解析的平台和 URL 是可自訂的。如需更多詳細資訊，請參閱 Daemon JVM 標準文件。

在 scala 擴展中明確宣告 Scala 版本

Scala 外掛程式 提供對編譯、測試和封裝 Scala 專案的支援。

從此版本的 Gradle 開始，當套用 scala-base 或 scala 外掛程式時，您現在可以在 scala 擴展中明確宣告 Scala 版本。這允許 Gradle 自動解析所需的 Scala 工具鏈依賴項，無需使用者手動宣告。它也消除了從生產環境執行時期類別路徑推斷 Scala 版本的需要，而這種方法很容易出錯。

現在，您可以在 scala 擴展中明確設定 Scala 版本，並且不再需要 scala-library 依賴項

plugins {
    id("scala")
}

repositories {
    mavenCentral()
}

scala {
    scalaVersion = "2.13.12"
    // OR 
    scalaVersion = "3.6.3"
}

先前，您必須宣告 scala-library 依賴項，如下所示

plugins {
    id("scala")
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.scala-lang:scala-library:2.13.12")
    // OR
    implementation("org.scala-lang:scala3-library_3:3.6.3")
}

有關使用 Scala 外掛程式的更多詳細資訊，請參閱文件。

JUnit XML 時間戳記中的額外精度

Gradle 提供內建支援來執行 JUnit 測試並產生詳細報告。由 test 任務產生的 JUnit XML 報告 現在在測試事件時間戳記中包含毫秒精度

<testsuite name="ExampleTest" tests="1" failures="0" errors="0" timestamp="2024-02-03T12:34:56.789" time="1.234">
    <testcase name="testExample" classname="com.example.ExampleTest" time="1.234">
    </testcase>
</testsuite>

此變更提高了分析測試執行時間的準確性，尤其是在精確計時至關重要的環境中。

有關 Gradle 中 JUnit 測試報告的更多詳細資訊，請參閱在 JVM 專案中進行測試。

建置撰寫改進

Gradle 為外掛程式作者和建置工程師提供 豐富的 API，以開發自訂建置邏輯。

ProjectLayout API 改進

ProjectLayout 類別提供對專案中目錄和檔案的存取。從此版本的 Gradle 開始，它還可以存取 settings directory（settings.gradle(.kts) 檔案的位置）。

雖然 settings directory 並非特定於任何專案，但某些用例需要相對於它解析檔案路徑

val versionFile = layout.settingsDirectory.file("version.txt")

先前，存取 settings directory 需要使用 rootProject.layout.projectDirectory。此方法涉及存取 rootProject 物件，這是不建議的做法，然後手動解析 settings directory 的路徑

val versionFile = rootProject.layout.projectDirectory.file("version.text")

新功能解決了一個常見的場景：解析在建置中所有專案之間共用的檔案，例如根資料夾中的 linting 配置或 version.txt 檔案。

有關更多詳細資訊，請參閱 ProjectLayout.getSettingsDirectory()。

新的 artifactTransforms 報告任務

Artifact Transforms 在依賴項解析過程中修改或轉換依賴項的 Artifact。

新的 artifactTransforms 任務可用，提供有關專案中所有已註冊的 Artifact Transforms 的資訊。

任務產生的報告可協助建置作者識別其專案中建置腳本和外掛程式註冊的轉換。檢視已註冊轉換的列表對於除錯 不明確轉換失敗 特別有用。

報告包含以下詳細資訊

• 實作轉換的 action 的完整類型名稱
• 轉換是否可快取
• 用於選擇轉換的完整輸入屬性集及其值
• 由轉換產生的完整輸出屬性集及其值

如需更多資訊，請參閱 ArtifactTransformsReportTask DSL 參考。

TestEventReporting API 改進

Gradle 提供 HTML 測試報告，以協助您了解和解決測試失敗問題。當將 test 任務與支援的測試框架（例如 JUnit）一起使用時，會自動產生此報告。

外掛程式作者和平台供應商現在可以利用 Test Event Reporting API 來捕獲測試事件並為在 Gradle 內建測試基礎架構之外執行的測試產生報告

public abstract class CustomTest extends DefaultTask {

    @Inject
    protected abstract ProjectLayout getLayout();
    
    @Inject
    protected abstract TestEventReporterFactory getTestEventReporterFactory();

    @TaskAction
    void runTests() {
        try (TestEventReporter test = getTestEventReporterFactory().createTestEventReporter(
                "custom-test",
                getLayout().getBuildDirectory().dir("test-results/custom-test").get(),
                getLayout().getBuildDirectory().dir("reports/tests/custom-test").get()
        )) {
            // Start the test
            test.started(Instant.now());

            // Execute custom test...
            
            // Report test outcome
            if (testFailureCount > 0) {
                test.failed(Instant.now());
            } else {
                test.succeeded(Instant.now());
            }
        }
    }
}

此整合允許自訂測試框架產生與 Gradle 內建報告格式一致的豐富 HTML 測試報告，從而增強可見性和可用性。

您可以在 Test Reporting API 中找到更多詳細資訊和範例程式碼。

以下各節重點介紹此 API 的兩個主要功能。

中繼資料支援

自訂測試可以包含中繼資料，以提供有關測試執行的補充資訊。

中繼資料會顯示在 HTML 測試報告中，以提高可見性

test.metadata(Instant.now(),"Parent class:", String.valueOf(result.getTestIdentifier().getParentId().get()));

巢狀結構支援

支援階層式巢狀結構，以邏輯方式將測試套件和個別測試分組。這確保了詳細且結構化的報告，並且豐富的中繼資料範圍限定於每個層級

try (GroupTestEventReporter outer = root.reportTestGroup("OuterNestingSuite")) {
    outer.started(Instant.now());
        try (GroupTestEventReporter inner = root.reportTestGroup("InnerNestingSuite")) {
            inner.started(Instant.now());
            try (TestEventReporter test = inner.reportTest("nestedTest", "nestedTest()")) {
                test.started(Instant.now());
                test.succeeded(Instant.now());
            }
            inner.succeeded(Instant.now());
    }
    outer.succeeded(Instant.now());
}

巢狀事件反映在 HTML 測試報告中，提供清晰的可追溯性。

適用於自訂發行版的新 distribution-base 外掛程式

Distribution 外掛程式 簡化了專案二進位檔、腳本和其他資源的封裝和發行。它會建立包含指定專案輸出的可發行封存檔（ZIP 或 TAR），並提供用於組裝和安裝發行版的任務。

Gradle 現在包含一個 distribution-base 外掛程式，它鏡像 Distribution 外掛程式的功能，但不新增預設發行版。相反地，現有的 distribution 外掛程式充當 distribution-base 外掛程式的包裝器，新增了預設的 main 發行版。

對於想要 Distribution 外掛程式的功能但不需要 main 發行版的外掛程式開發人員來說，distribution-base 外掛程式特別有用

plugins {
    id("distribution-base")
}

distributions {
    create("custom") {
        distributionBaseName = "customName"
        contents {
            from("src/customLocation")
        }
    }
}

如需更多詳細資訊，請參閱 Distribution 外掛程式文件。

已提升的功能

已提升的功能是指在先前版本的 Gradle 中處於孵化階段，但現在已受支援且受向後相容性約束的功能。有關更多資訊，請參閱使用者手冊中關於「功能生命週期」的部分。

以下是在此 Gradle 版本中已提升的功能。

Tooling API 中已提升的功能

Tooling API 是一個介面，允許外部工具（例如 IDE）與 Gradle 建置互動並控制 Gradle 建置。

用於非同步傳送資料到用戶端的 API，其中包括 BuildActionExecuter.setStreamedValueListener(StreamedValueListener) 方法、StreamedValueListener 類型以及 BuildController.send(Object) 方法已提升為穩定版本。

強型別 dependencies 區塊 API

Gradle 7.6 中引入的 強型別 dependencies 區塊 API 現在已部分穩定。版本目錄依賴項仍處於審查中，可能會進行變更。

Dependencies API 使外掛程式作者能夠建立自訂 DSL 樣式的 dependencies 區塊，類似於建置腳本中的頂層 dependencies 區塊。

已修正的問題

已知問題

已知問題是在此版本發行後發現的，與此版本中所做的變更直接相關的問題。

外部貢獻

我們樂於收到來自 Gradle 社群的貢獻。有關貢獻的資訊，請參閱 gradle.org/contribute。

問題回報

如果您發現此版本有問題，請在 GitHub Issues 上提交錯誤報告，並遵守我們的問題指南。如果您不確定是否遇到錯誤，請使用論壇。

我們希望您能透過 Gradle 建置幸福，並期待您透過 Twitter 或 GitHub 提供意見回饋。