Skip to content

配置 Gradle 项目 ​

要使用 Gradle 构建 Kotlin 项目, 你需要在构建脚本文件 build.gradle(.kts) 中添加 Kotlin Gradle 插件, 并在其中配置项目的依赖项。

要了解有关构建脚本内容的更多信息, 请访问探索构建脚本部分。

应用插件 ​

要应用 Kotlin Gradle 插件,请使用 Gradle 插件 DSL 中的 plugins{} 块:

kotlin
plugins {
    // 将 `<...>` 替换为适合目标环境的插件名称
    kotlin("<...>") version "2.4.21"
    // 例如,如果目标环境为 JVM:
    // kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    // 将 `<...>` 替换为适合目标环境的插件名称
    id 'org.jetbrains.kotlin.<...>' version '2.4.21'
    // 例如,如果目标环境为 JVM:
    // id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}

Kotlin Gradle 插件 (KGP) 与 Kotlin 使用相同的版本号。

配置项目时,请检查 Kotlin Gradle 插件 (KGP) 与可用 Gradle 版本的兼容性。 下表列出了 Gradle 和 Android Gradle 插件 (AGP) 的最低与最高完全支持版本:

KGP 版本Gradle 最低与最高版本AGP 最低与最高版本
2.4.20–2.4.217.6.3–9.7.08.5.2–9.3.1
2.4.0–2.4.107.6.3–9.5.08.5.2–9.1.0
2.3.20–2.3.217.6.3–9.3.08.2.2–9.0.0
2.3.107.6.3–9.0.08.2.2–9.0.0
2.3.07.6.3–9.0.08.2.2–8.13.0
2.2.20–2.2.217.6.3–8.147.3.1–8.11.1
2.2.0–2.2.107.6.3–8.147.3.1–8.10.0
2.1.20–2.1.217.6.3–8.12.17.3.1–8.7.2
2.1.0–2.1.107.6.3–8.10*7.3.1–8.7.2
2.0.20–2.0.216.8.3–8.8*7.1.3–8.5
2.0.06.8.3–8.57.1.3–8.3.1
1.9.20–1.9.256.8.3–8.1.14.2.2–8.1.0

*Kotlin 2.0.20–2.0.21 与 Kotlin 2.1.0–2.1.10 与最高至 8.6 的 Gradle 版本完全兼容。 Gradle 8.7–8.10 版本也受支持,但仅有一个例外:如果你使用了 Kotlin Multiplatform Gradle 插件, 在 JVM 目标中调用 withJava() 函数的多平台项目中可能会看到弃用警告。 欲了解更多信息,请参阅默认创建的 Java 源集。

你也可以使用最高至最新发布的 Gradle 与 AGP 版本,但如果这样做,请记住可能会遇到弃用警告,或者某些新功能可能无法正常工作。

例如,Kotlin Gradle 插件和 kotlin-multiplatform 插件 2.4.21 需要最低 7.6.3 的 Gradle 版本才能编译你的项目。

类似地,最高完全支持的版本为 9.7.0。它不包含已弃用的 Gradle 方法与属性,并支持所有当前的 Gradle 功能。

早期 KGP 版本 ​

KGP 版本Gradle 最低与最高版本AGP 最低与最高版本
1.9.0–1.9.106.8.3–7.6.04.2.2–7.4.0
1.8.20–1.8.226.8.3–7.6.04.1.3–7.4.0
1.8.0–1.8.116.8.3–7.3.34.1.3–7.2.1
1.7.20–1.7.226.7.1–7.1.13.6.4–7.0.4
1.7.0–1.7.106.7.1–7.0.23.4.3–7.0.2
1.6.20–1.6.216.1.1–7.0.23.4.3–7.0.2

项目中的 Kotlin Gradle 插件数据 ​

默认情况下,Kotlin Gradle 插件会将特定于项目的持久化数据存储在项目根目录的 .kotlin 目录中。

不要将 .kotlin 目录提交到版本控制中。 例如,如果使用的是 Git,请将 .kotlin 添加到项目的 .gitignore 文件中。

你可以在项目的 gradle.properties 文件中添加以下属性来配置该行为:

Gradle 属性描述
kotlin.project.persistent.dir配置项目级数据的存储位置。默认值:<project-root-directory>/.kotlin
kotlin.project.persistent.dir.gradle.disableWrite控制是否禁用向 .gradle 目录写入 Kotlin 数据(用于向后兼容较早的 IDEA 版本)。默认值:false

针对 JVM ​

要以 JVM 为目标,请应用 Kotlin JVM 插件。

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    id "org.jetbrains.kotlin.jvm" version "2.4.21"
}

在此块中,version 必须是文字,且无法从另一个构建脚本应用。

Kotlin 与 Java 源代码 ​

Kotlin 源代码和 Java 源代码可以存储在同一目录中,也可以放置在不同目录中。

默认约定是使用不同的目录:

text
project
    - src
        - main (root)
            - kotlin
            - java

不要将 Java .java 文件存储在 src/*/kotlin 目录中,因为这些 .java 文件将不会被编译。

你可以使用 src/main/java 代替。

如果不使用默认约定,则应更新相应的 sourceSets 属性:

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'
}

在构建模块中,你可能会有一些相关的编译任务,例如:

  • compileKotlin 与 compileJava
  • compileTestKotlin 与 compileTestJava

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) 文件中的任务级别进行配置:

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。

以下情况会导致 JVM 目标不兼容:

  • 显式设置了不同的 jvmTarget 与 targetCompatibility 值。
  • 使用默认配置,且你的 JDK 不等于 1.8。

让我们看一个 JVM 目标的默认配置:构建脚本中只有 Kotlin JVM 插件,且没有针对 JVM 目标的额外设置:

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    id "org.jetbrains.kotlin.jvm" version "2.4.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 工具链支持 ​

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 守护进程运行所基于的 JDK 上执行。 Java 工具链会:

  • 设置适用于 JVM 目标的 -jdk-home 选项。
  • 如果用户未显式设置 jvmTarget 选项,则将 compilerOptions.jvmTarget 设置为工具链的 JDK 版本。 如果用户未配置工具链,jvmTarget 字段将使用默认值。 详细了解 JVM 目标兼容性。
  • 设置任何 Java 编译、测试和 javadoc 任务所使用的工具链。
  • 影响 kapt 工作线程运行所基于的 JDK。

使用以下代码设置工具链。请将占位符 <MAJOR_JDK_VERSION> 替换为你希望使用的 JDK 版本:

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 编译任务将使用该工具链:

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) 中:

kotlin
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("1.0.0")
}
groovy
plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

请在 Gradle 网站上检查 foojay-resolver-convention 的版本是否与你的 Gradle 版本相符。

要了解 Gradle 使用的是哪个工具链,请使用日志级别 --info 运行 Gradle 构建, 并在输出中查找以 [KOTLIN] Kotlin compilation 'jdkHome' argument: 开头的字符串。 冒号后面的部分即为来自工具链的 JDK 版本。

要为特定任务设置任意(包括本地)JDK,请使用 Task DSL。

详细了解 Kotlin 插件中的 Gradle JVM 工具链支持。

使用 Task DSL 设置 JDK 版本 ​

Task DSL 允许为任何实现了 UsesKotlinJavaToolchain 接口的任务设置任意 JDK 版本。 目前,这些任务包括 KotlinCompile 和 KaptTask。 如果希望 Gradle 搜索主要 JDK 版本,请替换构建脚本中的 <MAJOR_JDK_VERSION> 占位符:

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
    )
}

关联编译器任务 ​

你可以通过在编译之间建立一种关联关系来_关联 (associate)_编译,使得一个编译可以使用另一个编译的编译输出。关联编译会在它们之间建立 internal 可见性。

Kotlin 编译器默认会关联某些编译,例如每个目标的 test 和 main 编译。 如果你需要表明某个自定义编译与另一个编译相关联,请创建你自己的关联编译。

为了让 IDE 支持用于推断源集之间可见性的关联编译,请将以下代码添加到你的 build.gradle(.kts) 中:

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:

kotlin
tasks.named("compileJava", JavaCompile::class.java) {
    // 将编译后的 Kotlin 类提供给 javac —— Java/Kotlin 混合源代码工作所需
    val mainOutput: FileCollection = sourceSets["main"].output
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        listOf("--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}")
    })
}
groovy
tasks.named("compileJava", JavaCompile.class) {
    // 将编译后的 Kotlin 类提供给 javac —— Java/Kotlin 混合源代码工作所需
    FileCollection mainOutput = sourceSets["main"].output
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            return ["--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}"]
        }
    })
}

像往常一样将 module-info.java 放入 src/main/java 目录中。

对于模块而言,Kotlin 文件中的包名应与 module-info.java 中的包名相同,以避免出现“package is empty or does not exist”构建失败。

详细了解:

其他详细信息 ​

禁用在编译任务中使用构件 ​

在某些罕见场景下,你可能会遇到由循环依赖错误导致的构建失败。例如,当你有多个编译,其中一个编译可以看到另一个编译的所有 internal 声明,且生成的构件依赖于这两个编译任务的输出时:

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 插件会注册所有任务,且不会在试运行 (dry run) 时对其进行配置。

编译任务 destinationDirectory 的非默认位置 ​

如果你重写了 Kotlin/JVM KotlinJvmCompile/KotlinCompile 任务的 destinationDirectory 位置, 请更新构建脚本。你需要在 JAR 文件中显式将 sourceSets.main.kotlin.classesDirectories 添加到 sourceSets.main.outputs:

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

针对多平台 ​

针对多平台的项目(称为多平台项目)需要使用 kotlin-multiplatform 插件。

kotlin-multiplatform 插件适用于 Gradle 7.6.3 或更高版本。

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

详细了解针对不同平台的 Kotlin Multiplatform 以及 面向 iOS 和 Android 的 Kotlin Multiplatform。

针对 Android ​

建议使用 Android Studio 创建 Android 应用程序。了解如何使用 Android Gradle 插件。

针对 Web ​

Kotlin 通过 Kotlin Multiplatform 为 Web 开发提供了两种方式:

  • 基于 JavaScript(使用 Kotlin/JS 编译器)
  • 基于 WebAssembly(使用 Kotlin/Wasm 编译器)

两种方式均使用 Kotlin Multiplatform 插件,但支持不同的用例。 以下各节介绍了如何在 Gradle 构建中配置每个目标以及何时使用它们。

针对 JavaScript ​

如果你的目标是满足以下需求,请使用 Kotlin/JS:

  • 与 JavaScript/TypeScript 代码库共享业务逻辑
  • 使用 Kotlin 构建不可共享的 Web 应用

要了解更多信息,请参阅 Web 开发。

当以 JavaScript 为目标时,请使用 kotlin-multiplatform 插件:

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

通过指定是在浏览器还是 Node.js 环境中运行来配置 JavaScript 目标:

kotlin
kotlin {
    js().browser {  // 或 js().nodejs
        /* ... */
    }
}

针对 WebAssembly ​

如果你希望跨多个平台共享逻辑和 UI,请使用 Kotlin/Wasm。要了解更多信息, 请参阅 Web 开发。

与 JavaScript 一样,针对 WebAssembly (Wasm) 时,请使用 kotlin-multiplatform 插件:

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

根据你的要求,你可以针对:

为 Web 浏览器或 Node.js 配置 wasmJs 目标:

kotlin
kotlin {
    wasmJs {
        browser { // 或 nodejs
            /* ... */
        }
    }
}

对于 WASI 环境,使用 Node.js 或 Wasmtime 配置 wasmWasi 目标:

kotlin
kotlin {
    wasmWasi {
        nodejs { // 或 wasmtime
            /* ... */
        }
    }
}

Web 目标的 Kotlin 与 Java 源代码 ​

KGP 仅适用于 Kotlin 文件,因此建议将 Kotlin 和 Java 文件分开存放(如果项目中包含 Java 文件)。如果不分开存储,请在 sourceSets{} 块中指定源文件夹:

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 接口:

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)的依赖项。

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

在顶层配置依赖项

你可以在多平台项目中使用顶层 dependencies {} 块配置通用依赖项。 在此处声明的依赖项的行为就像被添加到 commonMain 或 commonTest 源集中一样。

要使用顶层 dependencies {} 块,请在块前添加 @OptIn(ExperimentalKotlinGradlePluginApi::class) 注解以选择加入:

kotlin
kotlin {
    @OptIn(ExperimentalKotlinGradlePluginApi::class)
    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
    }
}
groovy
kotlin {
    dependencies {
        implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
    }
}

在对应目标的 sourceSets {} 块内添加平台特定的依赖项。

你可以在 YouTrack 中分享关于此功能的反馈。

依赖项类型 ​

根据你的需求选择依赖项类型。

类型描述何时使用
api同时在编译期间和运行时使用,并导出给库的使用者。如果当前模块的公共 API 中使用了依赖项中的任何类型,请使用 api 依赖项。
implementation在当前模块的编译期间和运行时使用,但不会暴露给依赖于具有 implementation 依赖项模块的其他模块进行编译。

用于模块内部逻辑所需的依赖项。

如果模块是未发布的终端应用程序,请使用 implementation 依赖项而不是 api 依赖项。

compileOnly用于当前模块的编译,在运行时不可用,在其他模块编译期间也不可用。用于在运行时具有第三方实现的 API。
runtimeOnly在运行时可用,但在任何模块的编译期间均不可见。

对标准库的依赖 ​

对标准库 (stdlib) 的依赖项会自动添加到每个源集中。使用的标准库版本与 Kotlin Gradle 插件的版本相同。

对于平台特定源集,使用库的对应平台特定变体,而通用标准库将添加到其余源集中。Kotlin Gradle 插件会根据你的 Gradle 构建脚本中的 compilerOptions.jvmTarget 编译器选项选择适当的 JVM 标准库。

如果你显式声明了标准库依赖项(例如,如果你需要不同的版本),Kotlin Gradle 插件不会覆盖它,也不会添加第二个标准库。

如果根本不需要标准库,可以在 gradle.properties 文件中添加以下 Gradle 属性:

none
kotlin.stdlib.default.dependency=false

传递依赖项的版本对齐 ​

从 Kotlin 标准库 1.9.20 版本开始,Gradle 会使用标准库中包含的元数据来自动对齐传递的 kotlin-stdlib-jdk7 和 kotlin-stdlib-jdk8 依赖项。

如果为 1.8.0 至 1.9.10 之间的任何 Kotlin 标准库版本添加依赖项,例如: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.4.21"))
    groovy
    implementation platform('org.jetbrains.kotlin:kotlin-bom:2.4.21')
  • 如果没有为标准库版本添加依赖项,但有两个不同的依赖项以传递方式引入了不同旧版本的 Kotlin 标准库,则可以显式要求这些传递库使用 2.4.21 版本:

    kotlin
    dependencies {
        constraints {
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
                version {
                    require("2.4.21")
                }
            }
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
                version {
                    require("2.4.21")
                }
            }
        }
    }
    groovy
    dependencies {
        constraints {
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
                version {
                    require("2.4.21")
                }
            }
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
                version {
                    require("2.4.21")
                }
            }
        }
    }
  • 如果为 Kotlin 标准库版本 2.4.21 添加了依赖项:implementation("org.jetbrains.kotlin:kotlin-stdlib:2.4.21"),并且使用了旧版本(早于 1.8.0)的 Kotlin Gradle 插件,请更新 Kotlin Gradle 插件以匹配标准库版本:

    kotlin
    plugins {
        // 将 `<...>` 替换为插件名称
        kotlin("<...>") version "2.4.21"
    }
    groovy
    plugins {
        // 将 `<...>` 替换为插件名称
        id "org.jetbrains.kotlin.<...>" version "2.4.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.4.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 实现。

kotlin
kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // 这会自动引入所有平台依赖项
        }
    }
}
groovy
kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // 这会自动引入所有平台依赖项
            }
        }
    }
}

你可以使用 Kotlin 模块依赖项的简写形式,例如将 "org.jetbrains.kotlin:kotlin-test" 简写为 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 Multiplatform 项目:

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 项目:

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:

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

如果需要某个 kotlinx 库作为平台特定依赖项,仍然可以在相应的平台源集中使用该库的基础构件名称:

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

声明仓库 ​

你可以声明公开可用的仓库来使用其开源依赖项。在 repositories{} 块中,设置仓库的名称:

kotlin
repositories {
    mavenCentral()
}
groovy
repositories {
    mavenCentral()
}

常用仓库包括 Maven Central 和 Google 的 Maven 仓库。

如果你也处理 Maven 项目,我们建议避免添加 mavenLocal() 作为仓库,因为在 Gradle 和 Maven 项目之间切换时可能会遇到问题。如果必须添加 mavenLocal() 仓库,请将其作为 repositories{} 块中的最后一个仓库添加。详细信息请参阅 使用 mavenLocal() 的情况。

如果需要在多个子项目中声明相同的仓库,请在 settings.gradle(.kts) 文件的 dependencyResolutionManagement{} 块中集中声明仓库:

kotlin
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
groovy
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

在子项目中声明的任何仓库都会覆盖集中声明的仓库。有关如何控制此行为以及有哪些可用选项的详细信息,请参阅 Gradle 文档。

Experimental

注册生成的源代码

注册生成的源代码有助于 IDE、第三方插件和其他工具区分生成的代码和常规源文件。 这有助于 IDE 等工具在 UI 中对生成的代码进行不同高亮显示,并在导入项目时触发生成任务。 使用 KotlinSourceSet 接口来注册生成的源代码。

要注册包含 Kotlin 文件的目录,请在 build.gradle.kts 文件中将 generatedKotlin 属性与 SourceDirectorySet 类型配合使用。例如:

kotlin
val generatorTask = project.tasks.register("generator") {
    val outputDirectory = project.layout.projectDirectory.dir("src/main/kotlinGen")
    outputs.dir(outputDirectory)
    doLast {
        outputDirectory.file("generated.kt").asFile.writeText(
            // language=kotlin
            """
            fun printHello() {
                println("hello")
            }
            """.trimIndent()
        )
    }
}

kotlin.sourceSets.getByName("main").generatedKotlin.srcDir(generatorTask)

此示例创建了一个新任务 generator,其输出目录为 "src/main/kotlinGen"。当任务运行时, doLast {} 任务操作会在输出目录中创建一个 generated.kt 文件。最后,该示例将任务的输出注册为生成的源代码。

如果你正在开发 Gradle 插件,可以使用 allKotlinSources 属性来访问在 KotlinSourceSet.kotlin 和 KotlinSourceSet.generatedKotlin 属性中注册的所有源代码。

最新变化 ​

详细了解: