配置 Gradle 项目

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

要了解更多关于构建脚本的内容，请访问探索构建脚本章节。

应用插件

要应用 Kotlin Gradle 插件，请使用 Gradle 插件 DSL 中的 plugins{} 代码块：

KotlinGroovy

kotlin

plugins {
    // 将 `<...>` 替换为适合你的目标环境的插件名称
    kotlin("<...>") version "2.2.10"
    // 例如，如果你的目标环境是 JVM：
    // kotlin("jvm") version "2.2.10"
}

groovy

plugins {
    // 将 `<...>` 替换为适合你的目标环境的插件名称
    id 'org.jetbrains.kotlin.<...>' version '2.2.10'
    // 例如，如果你的目标环境是 JVM： 
    // id 'org.jetbrains.kotlin.jvm' version '2.2.10'
}

Kotlin Gradle 插件 (KGP) 和 Kotlin 共享相同的版本号。

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

KGP 版本	Gradle 最低和最高版本	AGP 最低和最高版本
2.2.0	7.6.3–8.14	7.3.1–8.10.0
2.1.20–2.1.21	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

*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.2.10 要求你的项目编译时最低 Gradle 版本为 7.6.3。

同样，完全支持的最高版本是 8.14。它不包含弃用的 Gradle 方法和属性，并支持所有当前的 Gradle 特性。

项目中的 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 插件。

KotlinGroovy

kotlin

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

groovy

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

version 在此代码块中应为字面量，不能从另一个构建脚本中应用。

Kotlin 和 Java 源代码

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

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

text

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

不要将 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

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。

如果出现以下情况，就会发生 JVM 目标不兼容：

你显式设置了 jvmTarget 和 targetCompatibility 的不同值。
你有一个默认配置，并且你的 JDK 不等于 1.8。

让我们考虑一下，当你的构建脚本中只有 Kotlin JVM 插件且没有 JVM 目标的额外设置时，JVM 目标的默认配置：

KotlinGroovy

kotlin

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

groovy

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

当构建脚本中没有关于 jvmTarget 值的显式信息时，其默认值为 null，编译器会将其转换为默认值 1.8。targetCompatibility 等于当前 Gradle 的 JDK 版本，也就是你的 JDK 版本（除非你使用 Java 工具链方法）。假设你的 JDK 版本是 17，你发布的库 artifact 将声明自身兼容 JDK 17+：org.gradle.jvm.version=17，这是错误的。在这种情况下，你必须在主项目中使用 Java 17 来添加此库，即使字节码版本是 1.8。配置工具链来解决此问题。

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 并安装构建所需的缺失 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 任务使用的工具链。
影响哪些 JDK kapt worker 在其上运行。

使用以下代码来设置工具链。将占位符 <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 版本相对应。

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

要为特定任务设置任何 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 可见性。

为了使 IDE 支持关联的编译项以推断源代码集之间的可见性，请将以下代码添加到你的 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 {
        // 为 javac 提供已编译的 Kotlin 类 – 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() {
            // 为 javac 提供已编译的 Kotlin 类 – Java/Kotlin 混合源代码工作所需
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

像往常一样将 module-info.java 放入 src/main/java 目录中。
对于模块，Kotlin 文件中的包名应与 module-info.java 中的包名相同，以避免出现“package is empty or does not exist”的构建失败。

了解更多关于：

其他详情

了解更多关于 Kotlin/JVM。

禁用 artifact 在编译任务中的使用

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

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。此属性控制编译任务中 artifact 输入的使用，并确定是否因此创建任务依赖。

默认情况下，此属性设置为 true 以跟踪任务依赖。如果你遇到循环依赖错误，你可以禁用 artifact 在编译任务中的使用，从而移除任务依赖并避免循环依赖错误。

要禁用 artifact 在编译任务中的使用，请将以下内容添加到你的 gradle.properties 文件中：

kotlin

kotlin.build.archivesTaskOutputAsFriendModule=false

惰性 Kotlin/JVM 任务创建

从 Kotlin 1.8.20 开始，Kotlin Gradle 插件会注册所有任务，并且不在空运行 (dry run) 时配置它们。

编译任务的 `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 插件。

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

KotlinGroovy

kotlin

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

groovy

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

面向 Android

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

面向 JavaScript

面向 JavaScript 时，也请使用 kotlin-multiplatform 插件。了解更多关于设置 Kotlin/JS 项目

KotlinGroovy

kotlin

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

groovy

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

针对 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、多平台、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 依赖项。

如果你添加了对 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 的平台依赖：
KotlinGroovy
kotlin
implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.2.10"))
groovy
implementation platform('org.jetbrains.kotlin:kotlin-bom:2.2.10')

如果你没有添加对标准库版本的依赖项，但你有两个不同的依赖项通过传递性引入了不同旧版本的 Kotlin 标准库，那么你可以显式要求这些传递性库的 2.2.10 版本：

KotlinGroovy

kotlin

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

groovy

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

如果你添加了对 Kotlin 标准库 2.2.10 版本的依赖项：implementation("org.jetbrains.kotlin:kotlin-stdlib:2.2.10")，并且你的 Kotlin Gradle 插件版本较旧（早于 1.8.0），请更新 Kotlin Gradle 插件以匹配标准库版本：
KotlinGroovy
kotlin
plugins { // 将 `<...>` 替换为插件名称 kotlin("<...>") version "2.2.10" }
groovy
plugins { // 将 `<...>` 替换为插件名称 id "org.jetbrains.kotlin.<...>" version "2.2.10" }
如果你使用早于 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.2.10 或从引入它的库中排除传递性的 kotlin-stdlib:1.8+：
KotlinGroovy
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") // 这会自动引入所有平台依赖项
            }
        }
    }
}

你可以使用 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 库的依赖项

如果你使用多平台库并需要依赖共享代码，请在共享源代码集中只设置一次依赖项。使用库的基础 artifact 名称，例如 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 库用于平台特有的依赖项，你仍然可以在相应的平台源代码集中使用库的基础 artifact 名称：

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 版本库。

如果你也使用 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) ​

其他详情 ​

禁用 artifact 在编译任务中的使用 ​

惰性 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)

其他详情

禁用 artifact 在编译任务中的使用

惰性 Kotlin/JVM 任务创建

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

面向多平台

面向 Android

面向 JavaScript

针对 JavaScript 的 Kotlin 和 Java 源代码

使用 KotlinBasePlugin 接口触发配置操作

配置依赖项

依赖项类型

对标准库的依赖项

传递性依赖项的版本对齐

对齐版本的其他方法

设置对测试库的依赖项

`kotlin-test` 的 JVM 变体

设置对 kotlinx 库的依赖项

在顶层设置依赖项

声明版本库

下一步是什么？