設定 Gradle 專案

若要使用 Gradle 建構 Kotlin 專案，您需要將 Kotlin Gradle 外掛程式加入到您的建構腳本檔案 build.gradle(.kts) 中，並在其中設定專案的依賴項。

NOTE

若要深入了解建構腳本的內容，請參閱探索建構腳本章節。

應用外掛程式

若要應用 Kotlin Gradle 外掛程式，請使用 Gradle 外掛程式 DSL 中的 plugins{} 區塊：

KotlinGroovy

kotlin

plugins {
    // 將 <...> 替換為適合您目標環境的外掛程式名稱
    kotlin("<...>") version "2.1.21"
    // 例如，如果您的目標環境是 JVM：
    // kotlin("jvm") version "2.1.21"
}

groovy

plugins {
    // 將 <...> 替換為適合您目標環境的外掛程式名稱
    id 'org.jetbrains.kotlin.<...>' version '2.1.21'
    // 例如，如果您的目標環境是 JVM： 
    // id 'org.jetbrains.kotlin.jvm' version '2.1.21'
}

NOTE

Kotlin Gradle 外掛程式 (KGP) 和 Kotlin 共用相同的版本編號。

設定專案時，請檢查 Kotlin Gradle 外掛程式 (KGP) 與可用 Gradle 版本的相容性。下表列出了 Gradle 和 Android Gradle 外掛程式 (AGP) 的最低和最高完全支援版本：

KGP 版本	Gradle 最低與最高版本	AGP 最低與最高版本
2.1.20	7.6.3–8.12.1	7.3.1–8.7.2
2.1.0–2.1.10	7.6.3–8.10*	7.3.1–8.7.2
2.0.20–2.0.21	6.8.3–8.8*	7.1.3–8.5
2.0.0	6.8.3–8.5	7.1.3–8.3.1
1.9.20–1.9.25	6.8.3–8.1.1	4.2.2–8.1.0
1.9.0–1.9.10	6.8.3–7.6.0	4.2.2–7.4.0
1.8.20–1.8.22	6.8.3–7.6.0	4.1.3–7.4.0
1.8.0–1.8.11	6.8.3–7.3.3	4.1.3–7.2.1
1.7.20–1.7.22	6.7.1–7.1.1	3.6.4–7.0.4
1.7.0–1.7.10	6.7.1–7.0.2	3.4.3–7.0.2
1.6.20–1.6.21	6.1.1–7.0.2	3.4.3–7.0.2

DANGER

*Kotlin 2.0.20–2.0.21 和 Kotlin 2.1.0–2.1.10 與 Gradle 最高 8.6 版本完全相容。Gradle 8.7–8.10 版本也受支援，但僅有一個例外：如果您使用 Kotlin 多平台 Gradle 外掛程式，您可能會在呼叫 JVM 目標中的 withJava() 函數時，在多平台專案中看到棄用警告。更多資訊請參閱預設建立的 Java 原始碼集。

您也可以使用最新版本的 Gradle 和 AGP，但請注意，您可能會遇到棄用警告或某些新功能可能無法運作。

例如，Kotlin Gradle 外掛程式和 kotlin-multiplatform 外掛程式 2.1.21 要求您的專案最低 Gradle 版本為 7.6.3 才能編譯成功。

同樣地，最高完全支援版本為 8.12.1。它沒有已棄用的 Gradle 方法和屬性，並且支援所有當前的 Gradle 功能。

專案中的 Kotlin Gradle 外掛程式資料

預設情況下，Kotlin Gradle 外掛程式將持久性專案特定資料儲存在專案的根目錄，即 .kotlin 目錄中。

DANGER

請勿將 .kotlin 目錄提交到版本控制。例如，如果您使用 Git，請將 .kotlin 加入到您專案的 .gitignore 檔案中。

您可以將以下屬性加入到專案的 gradle.properties 檔案中以設定此行為：

Gradle 屬性	描述
`kotlin.project.persistent.dir`	設定專案層級資料的儲存位置。預設值：`<專案根目錄>/.kotlin`
`kotlin.project.persistent.dir.gradle.disableWrite`	控制是否禁止將 Kotlin 資料寫入 `.gradle` 目錄（用於與舊版 IDEA 的向後相容性）。預設值：false

目標 JVM

若要目標 JVM，請應用 Kotlin JVM 外掛程式。

KotlinGroovy

kotlin

plugins {
    kotlin("jvm") version "2.1.21"
}

groovy

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.1.21"
}

version 在此區塊中應為字面值，且不能從另一個建構腳本應用。

Kotlin 和 Java 原始碼

Kotlin 原始碼和 Java 原始碼可以儲存在同一目錄中，也可以放置在不同目錄中。

預設慣例是使用不同目錄：

text

專案
    - src
        - main (根目錄)
            - kotlin
            - java

DANGER

請勿將 Java .java 檔案儲存在 src/*/kotlin 目錄中，因為 .java 檔案將不會被編譯。

相反地，您可以使用 src/main/java。

如果您不使用預設慣例，則應更新對應的 sourceSets 屬性：

KotlinGroovy

kotlin

sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}

groovy

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

檢查相關編譯任務的 JVM 目標相容性

在建構模組中，您可能會有相關的編譯任務，例如：

compileKotlin 和 compileJava
compileTestKotlin 和 compileTestJava

NOTE

main 和 test 原始碼集編譯任務不相關。

對於此類相關任務，Kotlin Gradle 外掛程式會檢查 JVM 目標相容性。kotlin 擴充功能或任務中 jvmTarget 屬性和 java 擴充功能或任務中 targetCompatibility 的不同值會導致 JVM 目標不相容。例如： compileKotlin 任務的 jvmTarget=1.8，而 compileJava 任務具有（或繼承）targetCompatibility=15。

透過在 gradle.properties 檔案中將 kotlin.jvm.target.validation.mode 屬性設定為以下值，來設定整個專案的此檢查行為：

error – 外掛程式會使建構失敗；Gradle 8.0+ 專案的預設值。
warning – 外掛程式會印出警告訊息；Gradle 8.0 以下專案的預設值。
ignore – 外掛程式會跳過檢查且不產生任何訊息。

您也可以在 build.gradle(.kts) 檔案中於任務層級進行設定：

KotlinGroovy

kotlin

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}

groovy

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configureEach {
    jvmTargetValidationMode = org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING
}

為避免 JVM 目標不相容，請設定工具鏈或手動對齊 JVM 版本。

如果目標不相容會出什麼問題

手動設定 Kotlin 和 Java 原始碼集 JVM 目標有兩種方式：

透過設定 Java 工具鏈的隱式方式。
以及透過在 kotlin 擴充功能或任務中設定 jvmTarget 屬性，並在 java 擴充功能或任務中設定 targetCompatibility 的顯式方式。

如果您：

顯式設定了不同的 jvmTarget 和 targetCompatibility 值。
擁有預設設定，且您的 JDK 不等於 1.8。則會發生 JVM 目標不相容。

讓我們考慮一種預設的 JVM 目標設定，當您的建構腳本中只有 Kotlin JVM 外掛程式且沒有額外的 JVM 目標設定時：

KotlinGroovy

kotlin

plugins {
    kotlin("jvm") version "2.1.21"
}

groovy

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.1.21"
}

當建構腳本中沒有關於 jvmTarget 值的明確資訊時，其預設值為 null，且編譯器會將其翻譯為預設值 1.8。targetCompatibility 等於目前 Gradle 的 JDK 版本，這與您的 JDK 版本相同（除非您使用 Java 工具鏈方法）。假設您的 JDK 版本是 17，您發布的函式庫成品將宣告其相容於 JDK 17 +：org.gradle.jvm.version=17，這是錯誤的。在這種情況下，即使位元組碼的版本是 1.8，您也必須在主專案中使用 Java 17 來加入此函式庫。請設定工具鏈以解決此問題。

Gradle Java 工具鏈支援

DANGER

Android 使用者注意事項。若要使用 Gradle 工具鏈支援，請使用 Android Gradle 外掛程式 (AGP) 8.1.0-alpha09 或更高版本。

Gradle Java 工具鏈支援僅從 AGP 7.4.0 開始可用。

然而，由於此問題，AGP 直到 8.1.0-alpha09 版本才將 targetCompatibility 設定為與工具鏈的 JDK 相等。

如果您使用的版本低於 8.1.0-alpha09，您需要透過 compileOptions 手動設定 targetCompatibility。

將占位符號 <MAJOR_JDK_VERSION> 替換為您想要使用的 JDK 版本：

kotlin


android {

    compileOptions {

        sourceCompatibility = <MAJOR_JDK_VERSION>

        targetCompatibility = <MAJOR_JDK_VERSION>

    }

}

Gradle 6.7 引入了 Java 工具鏈支援。使用此功能，您可以：

使用與 Gradle 中不同的 JDK 和 JRE 來執行編譯、測試和可執行檔。
使用尚未發布的語言版本編譯和測試程式碼。

有了工具鏈支援，Gradle 可以自動偵測本地 JDK 並安裝 Gradle 建構所需的缺失 JDK。現在 Gradle 本身可以在任何 JDK 上執行，並且仍然可以重複使用依賴主要 JDK 版本的任務的遠端建構快取功能。

Kotlin Gradle 外掛程式支援 Kotlin/JVM 編譯任務的 Java 工具鏈。JS 和 Native 任務不使用工具鏈。 Kotlin 編譯器始終在 Gradle Daemon 執行的 JDK 上執行。 Java 工具鏈：

設定 JVM 目標可用的 -jdk-home 選項。
如果使用者未明確設定 jvmTarget 選項，則將 compilerOptions.jvmTarget 設定為工具鏈的 JDK 版本。如果使用者未設定工具鏈，jvmTarget 欄位會使用預設值。深入了解 JVM 目標相容性。
設定任何 Java 編譯、測試和 javadoc 任務要使用的工具鏈。
影響 kapt 工作器在哪個 JDK 上執行。

使用以下程式碼設定工具鏈。將占位符號 <MAJOR_JDK_VERSION> 替換為您想要使用的 JDK 版本：

KotlinGroovy

kotlin

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // 或者更短：
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例如：
    jvmToolchain(17)
}

groovy

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // 或者更短：
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例如：
    jvmToolchain(17)
}

請注意，透過 kotlin 擴充功能設定工具鏈也會更新 Java 編譯任務的工具鏈。

您可以透過 java 擴充功能設定工具鏈，Kotlin 編譯任務將會使用它：

KotlinGroovy

kotlin

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)) 
    }
}

groovy

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
}

如果您使用 Gradle 8.0.2 或更高版本，您還需要加入一個工具鏈解析器外掛程式。這種外掛程式管理從哪些儲存庫下載工具鏈。作為範例，請將以下外掛程式加入到您的 settings.gradle(.kts) 中：

KotlinGroovy

kotlin

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("0.9.0")
}

groovy

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.9.0'
}

請檢查 foojay-resolver-convention 的版本是否與 Gradle 網站上的 Gradle 版本相符。

NOTE

若要了解 Gradle 使用哪個工具鏈，請使用 --info 日誌層級執行您的 Gradle 建構，並在輸出中找到以 [KOTLIN] Kotlin compilation 'jdkHome' argument: 開頭的字串。冒號後的部分將會是來自工具鏈的 JDK 版本。

若要為特定任務設定任何 JDK（甚至是本地的），請使用任務 DSL。

深入了解 Kotlin 外掛程式中的 Gradle JVM 工具鏈支援。

使用任務 DSL 設定 JDK 版本

任務 DSL 允許為任何實作 UsesKotlinJavaToolchain 介面的任務設定任何 JDK 版本。目前，這些任務是 KotlinCompile 和 KaptTask。如果您想讓 Gradle 搜尋主要 JDK 版本，請替換建構腳本中的 <MAJOR_JDK_VERSION> 占位符號：

KotlinGroovy

kotlin

val service = project.extensions.getByType<JavaToolchainService>()
val customLauncher = service.launcherFor {
    languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
project.tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.toolchain.use(customLauncher)
}

groovy

JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class)
Provider<JavaLauncher> customLauncher = service.launcherFor {
    it.languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
tasks.withType(UsesKotlinJavaToolchain::class).configureEach { task ->
    task.kotlinJavaToolchain.toolchain.use(customLauncher)
}

或者您可以指定本地 JDK 的路徑，並將占位符號 <LOCAL_JDK_VERSION> 替換為此 JDK 版本：

kotlin

tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.jdk.use(
        "/path/to/local/jdk", // 放入您的 JDK 路徑
        JavaVersion.<LOCAL_JDK_VERSION> // 例如，JavaVersion.17
    )
}

關聯編譯器任務

您可以透過在編譯之間建立一種關係來_關聯_編譯，使得一個編譯使用另一個編譯的輸出。關聯編譯會在其間建立 internal 可見性。

Kotlin 編譯器預設會關聯一些編譯，例如每個目標的 test 和 main 編譯。如果您需要表達您的其中一個自訂編譯與另一個相關聯，請建立您自己的關聯編譯。

為使 IDE 支援關聯編譯以推斷原始碼集之間的 visibility，請將以下程式碼加入到您的 build.gradle(.kts) 中：

KotlinGroovy

kotlin

val integrationTestCompilation = kotlin.target.compilations.create("integrationTest") {
    associateWith(kotlin.target.compilations.getByName("main"))
}

groovy

integrationTestCompilation {
    kotlin.target.compilations.create("integrationTest") {
        associateWith(kotlin.target.compilations.getByName("main"))
    }
}

在此，integrationTest 編譯與 main 編譯關聯，這允許從功能測試存取 internal 物件。

啟用 Java 模組 (JPMS) 設定

為使 Kotlin Gradle 外掛程式與 Java 模組協同運作，請將以下行加入到您的建構腳本中，並將 YOUR_MODULE_NAME 替換為您的 JPMS 模組參考，例如 org.company.module：

KotlinGroovy

kotlin

// 如果您使用的 Gradle 版本低於 7.0，請加入以下三行
java {
    modularity.inferModulePath.set(true)
}

tasks.named("compileJava", JavaCompile::class.java) {
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        // 提供編譯過的 Kotlin 類別給 javac – Java/Kotlin 混合原始碼協同運作所需
        listOf("--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}")
    })
}

groovy

// 如果您使用的 Gradle 版本低於 7.0，請加入以下三行
java {
    modularity.inferModulePath = true
}

tasks.named("compileJava", JavaCompile.class) {
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            // 提供編譯過的 Kotlin 類別給 javac – Java/Kotlin 混合原始碼協同運作所需
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

NOTE

請照常將 module-info.java 放入 src/main/java 目錄中。

對於模組，Kotlin 檔案中的套件名稱應與 module-info.java 中的套件名稱相同，以避免「套件為空或不存在」的建構失敗。

深入了解：

其他細節

深入了解 Kotlin/JVM。

停用編譯任務中成品的使用

在某些少數情況下，您可能會遇到由循環依賴錯誤引起的建構失敗。例如，當您有多個編譯，其中一個編譯可以看到另一個編譯的所有內部宣告，並且產生的成品依賴於兩個編譯任務的輸出時：

none

FAILURE: Build failed with an exception.

What went wrong:
Circular dependency between the following tasks:
:lib:compileKotlinJvm
--- :lib:jvmJar
     \--- :lib:compileKotlinJvm (*)
(*) - details omitted (listed previously)

為了解決這個循環依賴錯誤，我們加入了 Gradle 屬性：archivesTaskOutputAsFriendModule。此屬性控制編譯任務中成品輸入的使用，並決定是否因此建立任務依賴項。

預設情況下，此屬性設定為 true 以追蹤任務依賴項。如果您遇到循環依賴錯誤，可以停用編譯任務中成品的使用，以移除任務依賴項並避免循環依賴錯誤。

若要停用編譯任務中成品的使用，請將以下內容加入到您的 gradle.properties 檔案中：

kotlin

kotlin.build.archivesTaskOutputAsFriendModule=false

延遲 Kotlin/JVM 任務建立

從 Kotlin 1.8.20 開始，Kotlin Gradle 外掛程式會註冊所有任務，且在空執行時不設定它們。

編譯任務 destinationDirectory 的非預設位置

如果您覆寫了 Kotlin/JVM KotlinJvmCompile/KotlinCompile 任務的 destinationDirectory 位置，請更新您的建構腳本。您需要明確地將 sourceSets.main.kotlin.classesDirectories 加入到 JAR 檔案中的 sourceSets.main.outputs：

kotlin

tasks.jar(type: Jar) {
    from sourceSets.main.outputs
    from sourceSets.main.kotlin.classesDirectories
}

目標多個平台

目標多個平台的專案，稱為多平台專案，需要 kotlin-multiplatform 外掛程式。

NOTE

kotlin-multiplatform 外掛程式適用於 Gradle 7.6.3 或更高版本。

KotlinGroovy

kotlin

plugins {
    kotlin("multiplatform") version "2.1.21"
}

groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.1.21'
}

深入了解針對不同平台的 Kotlin Multiplatform 和針對 iOS 和 Android 的 Kotlin Multiplatform。

目標 Android

建議使用 Android Studio 建立 Android 應用程式。了解如何使用 Android Gradle 外掛程式。

目標 JavaScript

目標 JavaScript 時，也要使用 kotlin-multiplatform 外掛程式。深入了解如何設定 Kotlin/JS 專案

KotlinGroovy

kotlin

plugins {
    kotlin("multiplatform") version "2.1.21"
}

groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.1.21'
}

JavaScript 的 Kotlin 和 Java 原始碼

此外掛程式僅適用於 Kotlin 檔案，因此建議您將 Kotlin 和 Java 檔案分開儲存（如果專案包含 Java 檔案）。如果您不單獨儲存它們，請在 sourceSets{} 區塊中指定原始碼資料夾：

KotlinGroovy

kotlin

kotlin {
    sourceSets["main"].apply {
        kotlin.srcDir("src/main/myKotlin")
    }
}

groovy

kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'src/main/myKotlin'
    }
}

使用 KotlinBasePlugin 介面觸發設定動作

若要觸發某些設定動作，每當應用任何 Kotlin Gradle 外掛程式（JVM、JS、Multiplatform、Native 等）時，請使用所有 Kotlin 外掛程式繼承的 KotlinBasePlugin 介面：

KotlinGroovy

kotlin

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType<KotlinBasePlugin>() {
    // 在此設定您的動作
}

groovy

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType(KotlinBasePlugin.class) {
    // 在此設定您的動作
}

設定依賴項

若要加入函式庫依賴項，請在原始碼集 DSL 的 dependencies{} 區塊中設定所需類型的依賴項（例如 implementation）。

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.example:my-library:1.0")
        }
    }
}

groovy

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'com.example:my-library:1.0'
            }
        }
    }
}

或者，您可以在頂層設定依賴項。

依賴項類型

根據您的要求選擇依賴項類型。

類型	描述	何時使用
`api`	在編譯和執行時使用，並匯出到函式庫的消費者。	如果依賴項中的任何類型在目前模組的公共 API 中使用，請使用 `api` 依賴項。
`implementation`	在目前模組的編譯和執行時使用，但不暴露給依賴於具有 `implementation` 依賴項的其他模組進行編譯。	用於模組內部邏輯所需的依賴項。如果模組是未發布的終端應用程式，請使用 `implementation` 依賴項而不是 `api` 依賴項。
`compileOnly`	用於目前模組的編譯，但在執行時和編譯其他模組時均不可用。	用於在執行時具有第三方實作的 API。
`runtimeOnly`	在執行時可用，但在任何模組編譯時均不可見。

標準函式庫依賴項

標準函式庫 (stdlib) 的依賴項會自動加入到每個原始碼集。所使用的標準函式庫版本與 Kotlin Gradle 外掛程式的版本相同。

對於平台特定原始碼集，會使用對應的平台特定函式庫變體，而通用標準函式庫則會加入到其餘部分。Kotlin Gradle 外掛程式會根據您 Gradle 建構腳本的 compilerOptions.jvmTarget 編譯器選項選擇適當的 JVM 標準函式庫。

如果您明確宣告標準函式庫依賴項（例如，如果您需要不同的版本），Kotlin Gradle 外掛程式將不會覆寫它或加入第二個標準函式庫。

如果您根本不需要標準函式庫，您可以將以下 Gradle 屬性加入到您的 gradle.properties 檔案中：

none

kotlin.stdlib.default.dependency=false

傳遞性依賴項的版本對齊

從 Kotlin 標準函式庫版本 1.9.20 開始，Gradle 使用標準函式庫中包含的中繼資料來自動對齊傳遞性 kotlin-stdlib-jdk7 和 kotlin-stdlib-jdk8 依賴項。

如果您為 Kotlin 標準函式庫的任何版本（介於 1.8.0 – 1.9.10 之間）加入依賴項，例如：implementation("org.jetbrains.kotlin:kotlin-stdlib:1.8.0")，則 Kotlin Gradle 外掛程式會將此 Kotlin 版本用於傳遞性 kotlin-stdlib-jdk7 和 kotlin-stdlib-jdk8 依賴項。這避免了來自不同標準函式庫版本的類別重複。深入了解如何將 kotlin-stdlib-jdk7 和 kotlin-stdlib-jdk8 合併到 kotlin-stdlib 中。您可以在 gradle.properties 檔案中透過 kotlin.stdlib.jdk.variants.version.alignment Gradle 屬性停用此行為：

none

kotlin.stdlib.jdk.variants.version.alignment=false

其他版本對齊方式

如果您有版本對齊問題，可以透過 Kotlin BOM 對齊所有版本。在您的建構腳本中宣告對 kotlin-bom 的平台依賴項：

kotlin

  implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.1.21"))

groovy

  implementation platform('org.jetbrains.kotlin:kotlin-bom:2.1.21')

:::

如果您沒有為標準函式庫版本加入依賴項，但您有兩個不同的依賴項，它們傳遞性地引入了不同舊版本的 Kotlin 標準函式庫，那麼您可以明確要求這些傳遞性函式庫的 2.1.21 版本：

kotlin

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.1.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.1.21")
              }
          }
      }
  }

groovy

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.1.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.1.21")
              }
          }
      }
  }

:::

如果您為 Kotlin 標準函式庫版本 2.1.21 加入依賴項：implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.21")，並且 Kotlin Gradle 外掛程式是舊版本（早於 1.8.0），請更新 Kotlin Gradle 外掛程式以符合標準函式庫版本：

kotlin

  plugins {
      // 將 <...> 替換為外掛程式名稱
      kotlin("<...>") version "2.1.21"
  }

groovy

  plugins {
      // 將 <...> 替換為外掛程式名稱
      id "org.jetbrains.kotlin.<...>" version "2.1.21"
  }

:::

如果您使用早於 1.8.0 版本的 kotlin-stdlib-jdk7/kotlin-stdlib-jdk8，例如 implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:SOME_OLD_KOTLIN_VERSION")，並且有一個依賴項傳遞性地引入了 kotlin-stdlib:1.8+，請將您的 kotlin-stdlib-jdk<7/8>:SOME_OLD_KOTLIN_VERSION 替換為 kotlin-stdlib-jdk*:2.1.21 或排除引入它的函式庫中的傳遞性 kotlin-stdlib:1.8+：

kotlin

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib")
      }
  }

groovy

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib"
      }
  }

:::

設定測試函式庫依賴項

kotlin.test API 可用於測試所有支援平台上的 Kotlin 專案。將 kotlin-test 依賴項加入到 commonTest 原始碼集，以便 Gradle 外掛程式可以推斷每個測試原始碼集的對應測試依賴項。

Kotlin/Native 目標不需要額外的測試依賴項，且 kotlin.test API 的實作是內建的。

KotlinGroovy

kotlin

kotlin {
    sourceSets {
         commonTest.dependencies {
             implementation(kotlin("test")) // 這會自動引入所有平台依賴項
        }
    }
}

groovy

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // 這會自動引入所有平台依賴項
            }
        }
    }
}

NOTE

您可以使用 Kotlin 模組依賴項的簡寫，例如，kotlin("test") 代表 "org.jetbrains.kotlin:kotlin-test"。

您也可以在任何共用或平台特定原始碼集中使用 kotlin-test 依賴項。

kotlin-test 的 JVM 變體

對於 Kotlin/JVM，Gradle 預設使用 JUnit 4。因此，kotlin("test") 依賴項會解析為 JUnit 4 的變體，即 kotlin-test-junit。

您可以透過在建構腳本的測試任務中呼叫 useJUnitPlatform() 或 useTestNG() 來選擇 JUnit 5 或 TestNG。以下範例適用於 Kotlin 多平台專案：

KotlinGroovy

kotlin

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

groovy

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test")
            }
        }
    }
}

以下範例適用於 JVM 專案：

KotlinGroovy

kotlin

dependencies {
    testImplementation(kotlin("test"))
}

tasks {
    test {
        useTestNG()
    }
}

groovy

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

test {
    useTestNG()
}

了解如何在 JVM 上使用 JUnit 測試程式碼。

自動 JVM 變體解析有時可能導致您的設定出現問題。在這種情況下，您可以明確指定所需的框架，並透過將此行加入到專案的 gradle.properties 檔案中來停用自動解析：

text

kotlin.test.infer.jvm.variant=false

如果您在建構腳本中明確使用了 kotlin("test") 的變體，並且您的專案建構因相容性衝突而停止運作，請參閱相容性指南中的此問題。

設定 kotlinx 函式庫依賴項

如果您使用多平台函式庫且需要依賴共用程式碼，請在共用原始碼集中僅設定一次依賴項。使用函式庫的基本成品名稱，例如 kotlinx-coroutines-core 或 ktor-client-core：

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

groovy

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

如果您需要用於平台特定依賴項的 kotlinx 函式庫，您仍然可以在對應的平台原始碼集中使用函式庫的基本成品名稱：

KotlinGroovy

kotlin

kotlin {
    sourceSets {
        jvmMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

groovy

kotlin {
    sourceSets {
        jvmMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

在頂層設定依賴項

或者，您可以在頂層指定依賴項，使用以下模式設定名稱：<sourceSetName><DependencyType>。這對於某些 Gradle 內建依賴項（如 gradleApi()、localGroovy() 或 gradleTestKit()）可能很有幫助，這些依賴項在原始碼集的依賴項 DSL 中不可用。

KotlinGroovy

kotlin

dependencies {
    "commonMainImplementation"("com.example:my-library:1.0")
}

groovy

dependencies {
    commonMainImplementation 'com.example:my-library:1.0'
}

宣告儲存庫

您可以宣告一個公開可用的儲存庫來使用其開源依賴項。在 repositories{} 區塊中，設定儲存庫的名稱：

KotlinGroovy

kotlin

repositories {
    mavenCentral()
}

groovy

repositories {
    mavenCentral()
}

熱門的儲存庫是 Maven Central 和 Google 的 Maven 儲存庫。

DANGER

如果您也使用 Maven 專案，我們建議避免將 mavenLocal() 作為儲存庫加入，因為在 Gradle 和 Maven 專案之間切換時，您可能會遇到問題。如果您必須加入 mavenLocal() 儲存庫，請將其作為 repositories{} 區塊中的最後一個儲存庫加入。更多資訊請參閱mavenLocal() 的用例。

如果您需要在多個子專案中宣告相同的儲存庫，請在您的 settings.gradle(.kts) 檔案中的 dependencyResolutionManagement{} 區塊中集中宣告儲存庫：

KotlinGroovy

kotlin

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

kotlin

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

子專案中宣告的任何儲存庫都會覆寫集中宣告的儲存庫。更多關於如何控制此行為和可用選項的資訊，請參閱 Gradle 的文件。

接下來是什麼？

深入了解：

使用 Spring Boot 建立 RESTful Web 服務和資料庫

設定 Gradle 專案 ​

應用外掛程式 ​

專案中的 Kotlin Gradle 外掛程式資料 ​

目標 JVM ​

Kotlin 和 Java 原始碼 ​

檢查相關編譯任務的 JVM 目標相容性 ​

如果目標不相容會出什麼問題 ​

Gradle Java 工具鏈支援 ​

使用任務 DSL 設定 JDK 版本 ​

關聯編譯器任務 ​

啟用 Java 模組 (JPMS) 設定 ​

其他細節 ​

停用編譯任務中成品的使用 ​

延遲 Kotlin/JVM 任務建立 ​

編譯任務 destinationDirectory 的非預設位置 ​

目標多個平台 ​

目標 Android ​

目標 JavaScript ​

JavaScript 的 Kotlin 和 Java 原始碼 ​

使用 KotlinBasePlugin 介面觸發設定動作 ​

設定依賴項 ​

依賴項類型 ​

標準函式庫依賴項 ​

傳遞性依賴項的版本對齊 ​

其他版本對齊方式 ​

設定測試函式庫依賴項 ​

kotlin-test 的 JVM 變體 ​

設定 kotlinx 函式庫依賴項 ​

在頂層設定依賴項 ​

宣告儲存庫 ​

接下來是什麼？ ​

設定 Gradle 專案

應用外掛程式

專案中的 Kotlin Gradle 外掛程式資料

目標 JVM

Kotlin 和 Java 原始碼

檢查相關編譯任務的 JVM 目標相容性

如果目標不相容會出什麼問題

Gradle Java 工具鏈支援

使用任務 DSL 設定 JDK 版本

關聯編譯器任務

啟用 Java 模組 (JPMS) 設定

其他細節

停用編譯任務中成品的使用

延遲 Kotlin/JVM 任務建立

編譯任務 destinationDirectory 的非預設位置

目標多個平台

目標 Android

目標 JavaScript

JavaScript 的 Kotlin 和 Java 原始碼

使用 KotlinBasePlugin 介面觸發設定動作

設定依賴項

依賴項類型

標準函式庫依賴項

傳遞性依賴項的版本對齊

其他版本對齊方式

設定測試函式庫依賴項

kotlin-test 的 JVM 變體

設定 kotlinx 函式庫依賴項

在頂層設定依賴項

宣告儲存庫

接下來是什麼？