配置 Gradle 项目
要使用 Gradle 构建 Kotlin 项目, 你需要在构建脚本文件 build.gradle(.kts) 中添加 Kotlin Gradle 插件, 并在其中配置项目的依赖项。
要了解有关构建脚本内容的更多信息, 请访问探索构建脚本部分。
应用插件
要应用 Kotlin Gradle 插件,请使用 Gradle 插件 DSL 中的 plugins{} 块:
plugins {
// 将 `<...>` 替换为适合目标环境的插件名称
kotlin("<...>") version "2.4.21"
// 例如,如果目标环境为 JVM:
// kotlin("jvm") version "2.4.21"
}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.21 | 7.6.3–9.7.0 | 8.5.2–9.3.1 |
| 2.4.0–2.4.10 | 7.6.3–9.5.0 | 8.5.2–9.1.0 |
| 2.3.20–2.3.21 | 7.6.3–9.3.0 | 8.2.2–9.0.0 |
| 2.3.10 | 7.6.3–9.0.0 | 8.2.2–9.0.0 |
| 2.3.0 | 7.6.3–9.0.0 | 8.2.2–8.13.0 |
| 2.2.20–2.2.21 | 7.6.3–8.14 | 7.3.1–8.11.1 |
| 2.2.0–2.2.10 | 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 |
*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.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 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 插件。
plugins {
kotlin("jvm") version "2.4.21"
}plugins {
id "org.jetbrains.kotlin.jvm" version "2.4.21"
}在此块中,version 必须是文字,且无法从另一个构建脚本应用。
Kotlin 与 Java 源代码
Kotlin 源代码和 Java 源代码可以存储在同一目录中,也可以放置在不同目录中。
默认约定是使用不同的目录:
project
- src
- main (root)
- kotlin
- java不要将 Java .java 文件存储在 src/*/kotlin 目录中,因为这些 .java 文件将不会被编译。
你可以使用 src/main/java 代替。
如果不使用默认约定,则应更新相应的 sourceSets 属性:
sourceSets.main {
java.srcDirs("src/main/myJava", "src/main/myKotlin")
}sourceSets {
main.kotlin.srcDirs += 'src/main/myKotlin'
main.java.srcDirs += 'src/main/myJava'
}检查相关编译任务的 JVM 目标兼容性
在构建模块中,你可能会有一些相关的编译任务,例如:
compileKotlin与compileJavacompileTestKotlin与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) 文件中的任务级别进行配置:
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}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 目标的额外设置:
plugins {
kotlin("jvm") version "2.4.21"
}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 版本:
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 {
jvmToolchain {
languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
// 或者简写为:
jvmToolchain(<MAJOR_JDK_VERSION>)
// 例如:
jvmToolchain(17)
}kotlin {
jvmToolchain {
languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
// 或者简写为:
jvmToolchain(<MAJOR_JDK_VERSION>)
// 例如:
jvmToolchain(17)
}注意,通过 kotlin 扩展设置工具链也会同时更新 Java 编译任务的工具链。
你也可以通过 java 扩展设置工具链,Kotlin 编译任务将使用该工具链:
java {
toolchain {
languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
}java {
toolchain {
languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
}如果你使用的是 Gradle 8.0.2 或更高版本,还需要添加工具链解析器插件。 此类插件用于管理从哪些仓库下载工具链。作为示例,请将以下插件添加到你的 settings.gradle(.kts) 中:
plugins {
id("org.gradle.toolchains.foojay-resolver-convention") version("1.0.0")
}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> 占位符:
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)
}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 版本:
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) 中:
val integrationTestCompilation = kotlin.target.compilations.create("integrationTest") {
associateWith(kotlin.target.compilations.getByName("main"))
}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:
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}")
})
}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 声明,且生成的构件依赖于这两个编译任务的输出时:
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.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:
tasks.jar(type: Jar) {
from sourceSets.main.outputs
from sourceSets.main.kotlin.classesDirectories
}针对多平台
针对多平台的项目(称为多平台项目)需要使用 kotlin-multiplatform 插件。
kotlin-multiplatform 插件适用于 Gradle 7.6.3 或更高版本。
plugins {
kotlin("multiplatform") version "2.4.21"
}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 插件:
plugins {
kotlin("multiplatform") version "2.4.21"
}plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}通过指定是在浏览器还是 Node.js 环境中运行来配置 JavaScript 目标:
kotlin {
js().browser { // 或 js().nodejs
/* ... */
}
}针对 WebAssembly
如果你希望跨多个平台共享逻辑和 UI,请使用 Kotlin/Wasm。要了解更多信息, 请参阅 Web 开发。
与 JavaScript 一样,针对 WebAssembly (Wasm) 时,请使用 kotlin-multiplatform 插件:
plugins {
kotlin("multiplatform") version "2.4.21"
}plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}根据你的要求,你可以针对:
wasmJs:用于在浏览器或 Node.js 中运行wasmWasi:用于在支持 WASI (WebAssembly System Interface) 的 Wasm 环境中运行,例如 Wasmtime、WasmEdge 等。
为 Web 浏览器或 Node.js 配置 wasmJs 目标:
kotlin {
wasmJs {
browser { // 或 nodejs
/* ... */
}
}
}对于 WASI 环境,使用 Node.js 或 Wasmtime 配置 wasmWasi 目标:
kotlin {
wasmWasi {
nodejs { // 或 wasmtime
/* ... */
}
}
}Web 目标的 Kotlin 与 Java 源代码
KGP 仅适用于 Kotlin 文件,因此建议将 Kotlin 和 Java 文件分开存放(如果项目中包含 Java 文件)。如果不分开存储,请在 sourceSets{} 块中指定源文件夹:
kotlin {
sourceSets["main"].apply {
kotlin.srcDir("src/main/myKotlin")
}
}kotlin {
sourceSets {
main.kotlin.srcDirs += 'src/main/myKotlin'
}
}使用 KotlinBasePlugin 接口触发配置操作
要在应用任何 Kotlin Gradle 插件(JVM、JS、Multiplatform、Native 等)时触发某些配置操作, 请使用所有 Kotlin 插件都继承自的 KotlinBasePlugin 接口:
import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin
// ...
project.plugins.withType<KotlinBasePlugin>() {
// 在此处配置你的操作
}import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin
// ...
project.plugins.withType(KotlinBasePlugin.class) {
// 在此处配置你的操作
}配置依赖项
要添加对库的依赖项,请在源集 DSL 的 dependencies{} 块中设置所需类型(例如 implementation)的依赖项。
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.example:my-library:1.0")
}
}
}kotlin {
sourceSets {
commonMain {
dependencies {
implementation 'com.example:my-library:1.0'
}
}
}
}在顶层配置依赖项
你可以在多平台项目中使用顶层 dependencies {} 块配置通用依赖项。 在此处声明的依赖项的行为就像被添加到 commonMain 或 commonTest 源集中一样。
要使用顶层 dependencies {} 块,请在块前添加 @OptIn(ExperimentalKotlinGradlePluginApi::class) 注解以选择加入:
kotlin {
@OptIn(ExperimentalKotlinGradlePluginApi::class)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}kotlin {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}在对应目标的 sourceSets {} 块内添加平台特定的依赖项。
你可以在 YouTrack 中分享关于此功能的反馈。
依赖项类型
根据你的需求选择依赖项类型。
| 类型 | 描述 | 何时使用 |
|---|---|---|
api | 同时在编译期间和运行时使用,并导出给库的使用者。 | 如果当前模块的公共 API 中使用了依赖项中的任何类型,请使用 api 依赖项。 |
implementation | 在当前模块的编译期间和运行时使用,但不会暴露给依赖于具有 implementation 依赖项模块的其他模块进行编译。 | 用于模块内部逻辑所需的依赖项。 如果模块是未发布的终端应用程序,请使用 |
compileOnly | 用于当前模块的编译,在运行时不可用,在其他模块编译期间也不可用。 | 用于在运行时具有第三方实现的 API。 |
runtimeOnly | 在运行时可用,但在任何模块的编译期间均不可见。 |
对标准库的依赖
对标准库 (stdlib) 的依赖项会自动添加到每个源集中。使用的标准库版本与 Kotlin Gradle 插件的版本相同。
对于平台特定源集,使用库的对应平台特定变体,而通用标准库将添加到其余源集中。Kotlin Gradle 插件会根据你的 Gradle 构建脚本中的 compilerOptions.jvmTarget 编译器选项选择适当的 JVM 标准库。
如果你显式声明了标准库依赖项(例如,如果你需要不同的版本),Kotlin Gradle 插件不会覆盖它,也不会添加第二个标准库。
如果根本不需要标准库,可以在 gradle.properties 文件中添加以下 Gradle 属性:
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 属性来禁用此行为:
kotlin.stdlib.jdk.variants.version.alignment=false对齐版本的其他方式
如果在版本对齐方面遇到问题,可以通过 Kotlin BOM 对齐所有版本。在构建脚本中声明对
kotlin-bom的平台依赖项:kotlinimplementation(platform("org.jetbrains.kotlin:kotlin-bom:2.4.21"))groovyimplementation platform('org.jetbrains.kotlin:kotlin-bom:2.4.21')如果没有为标准库版本添加依赖项,但有两个不同的依赖项以传递方式引入了不同旧版本的 Kotlin 标准库,则可以显式要求这些传递库使用
2.4.21版本:kotlindependencies { 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") } } } }groovydependencies { 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 插件以匹配标准库版本:kotlinplugins { // 将 `<...>` 替换为插件名称 kotlin("<...>") version "2.4.21" }groovyplugins { // 将 `<...>` 替换为插件名称 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+:kotlindependencies { implementation("com.example:lib:1.0") { exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib") } }groovydependencies { 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 {
sourceSets {
commonTest.dependencies {
implementation(kotlin("test")) // 这会自动引入所有平台依赖项
}
}
}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 {
jvm {
testRuns["test"].executionTask.configure {
useJUnitPlatform()
}
}
sourceSets {
commonTest.dependencies {
implementation(kotlin("test"))
}
}
}kotlin {
jvm {
testRuns["test"].executionTask.configure {
useJUnitPlatform()
}
}
sourceSets {
commonTest {
dependencies {
implementation kotlin("test")
}
}
}
}以下示例针对 JVM 项目:
dependencies {
testImplementation(kotlin("test"))
}
tasks {
test {
useTestNG()
}
}dependencies {
testImplementation 'org.jetbrains.kotlin:kotlin-test'
}
test {
useTestNG()
}自动解析 JVM 变体有时可能会给配置带来问题。在这种情况下,可以显式指定所需的框架,并通过在项目 gradle.properties 文件中添加以下行来禁用自动解析:
kotlin.test.infer.jvm.variant=false如果你在构建脚本中显式使用了 kotlin("test") 的变体,且项目构建因兼容性冲突而中断, 请参阅兼容性指南中的此问题。
设置对 kotlinx 库的依赖项
如果使用多平台库并且需要依赖共享代码,请仅在共享源集中设置一次依赖项。使用库的基础构件名称,例如 kotlinx-coroutines-core 或 ktor-client-core:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}
}kotlin {
sourceSets {
commonMain {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}
}
}如果需要某个 kotlinx 库作为平台特定依赖项,仍然可以在相应的平台源集中使用该库的基础构件名称:
kotlin {
sourceSets {
jvmMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}
}kotlin {
sourceSets {
jvmMain {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}
}
}声明仓库
你可以声明公开可用的仓库来使用其开源依赖项。在 repositories{} 块中,设置仓库的名称:
repositories {
mavenCentral()
}repositories {
mavenCentral()
}常用仓库包括 Maven Central 和 Google 的 Maven 仓库。
如果你也处理 Maven 项目,我们建议避免添加 mavenLocal() 作为仓库,因为在 Gradle 和 Maven 项目之间切换时可能会遇到问题。如果必须添加 mavenLocal() 仓库,请将其作为 repositories{} 块中的最后一个仓库添加。详细信息请参阅 使用 mavenLocal() 的情况。
如果需要在多个子项目中声明相同的仓库,请在 settings.gradle(.kts) 文件的 dependencyResolutionManagement{} 块中集中声明仓库:
dependencyResolutionManagement {
repositories {
mavenCentral()
}
}dependencyResolutionManagement {
repositories {
mavenCentral()
}
}在子项目中声明的任何仓库都会覆盖集中声明的仓库。有关如何控制此行为以及有哪些可用选项的详细信息,请参阅 Gradle 文档。
注册生成的源代码
注册生成的源代码有助于 IDE、第三方插件和其他工具区分生成的代码和常规源文件。 这有助于 IDE 等工具在 UI 中对生成的代码进行不同高亮显示,并在导入项目时触发生成任务。 使用 KotlinSourceSet 接口来注册生成的源代码。
要注册包含 Kotlin 文件的目录,请在 build.gradle.kts 文件中将 generatedKotlin 属性与 SourceDirectorySet 类型配合使用。例如:
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 属性中注册的所有源代码。
最新变化
详细了解:
