Kotlin 2.4.20 最新变化
有关错误修复版本 2.4.21 的详细信息,请参阅更新日志
Kotlin 2.4.20 现已发布!以下是本次发行的重点亮点:
- 标准库: 支持协程堆栈跟踪恢复、用于检查集合元素相等性与唯一性的新函数,以及用于
kotlin.test断言函数的新重载 - Kotlin/Native: 新增 Swift 导出功能、改进的增量编译,以及为 SwiftPM 依赖自动生成的
Package.swift文件 - Kotlin/Wasm: 调整
@JsFun声明中的顶层require()调用、改进伴生对象的初始化顺序、Kotlin Gradle 插件支持 Wasmtime、新增编译模式,以及缩减函数式接口的二进制大小 - Kotlin/JS: 用于浏览器测试的新 DSL、支持将挂起 lambda 导出为 async 函数、改进数据类的可导出性
- Gradle: 支持 Gradle 9.7.0 以及改进 Problems API 中的报告
- 构建工具 API (Build tools API): 支持新目标:Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据
- Kotlin 编译器:
kotlinr运行器命令和独立的原生镜像 (native image)
您还可以在此视频中查看更新概述:
有关 Kotlin 发行周期的信息,请参阅 Kotlin 发行流程。
更新至 Kotlin 2.4.20
最新版本的 Kotlin 已包含在最新版本的 IntelliJ IDEA 和 Android Studio 中。
要更新到新的 Kotlin 版本,请确保您的 IDE 已更新至最新版本,并在构建脚本中将 Kotlin 版本更改为 2.4.20。
新功能
Kotlin 2.2.20 引入了在 JVM 21 及更高版本上使用 invokedynamic 编译 when 表达式的实验性支持。
在 Kotlin 2.4.20 中,该功能现已晋升为稳定版 (Stable)并默认启用。
有关更多信息,请参阅文档。
新功能
此版本中提供了以下处于预稳定状态的功能,包括处于 Beta、Alpha 和 Experimental 状态的功能:
- 标准库:支持协程堆栈跟踪恢复
- 标准库:用于检查集合元素相等性与唯一性的新函数
- 标准库:用于
kotlin.test断言函数的新重载 - Kotlin/Native:新增 Swift 导出功能
- Kotlin/Native:改进
klib工件的增量编译 - Kotlin/JS:用于浏览器测试的新 DSL
- Kotlin/JS:支持将挂起 lambda 导出为 async 函数
- 构建工具 API:支持 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据
- Kotlin 编译器:独立的原生镜像
标准库
Kotlin 2.4.20 增加了对协程堆栈跟踪恢复的支持,引入了用于检查集合元素相等性与唯一性的新函数,并为 kotlin.test 断言函数提供了新重载。
支持协程堆栈跟踪恢复
Kotlin 2.4.20 在标准库中添加了 StackTraceRecoverable 接口。这改善了与 kotlinx.coroutines 库的集成,因为它允许您定义如何为堆栈跟踪恢复创建新的异常实例,而无需添加对 kotlinx.coroutines 的依赖。
当一个协程抛出异常而另一个协程重新抛出该异常时,堆栈跟踪恢复有助于调试。 它可以让您查看到异常的最初发生位置以及另一个协程重新抛出它的位置。
kotlinx.coroutines 库通过创建包含额外协程堆栈跟踪信息的新异常实例来执行堆栈跟踪恢复。 对于构造函数仅接受异常消息、原因 (cause)、二者兼有或不接受实参的异常,这一过程会自动发生。
如果异常构造函数具有其他必需的实参(例如行号或错误代码),请实现 StackTraceRecoverable 接口以定义 kotlinx.coroutines 库如何创建该异常的新实例。
要实现该接口,请重写 copyForStackTraceRecovery() 函数。在重写中,返回一个用于堆栈跟踪恢复的新异常实例;如果您不希望 kotlinx.coroutines 库复制该异常,则返回 null。
StackTraceRecoverable 接口在所有目标平台上均可用,但 kotlinx.coroutines 库仅在 JVM 上将其用于堆栈跟踪恢复。
这些 API 属于实验性 (Experimental),需要使用 @OptIn(ExperimentalStdlibCoroutineSupportApi::class) 注解进行选择加入 (opt-in)。
以下是一个自定义异常的示例,该异常在为堆栈跟踪恢复创建新实例时会保留 line 属性:
import kotlin.coroutines.ExperimentalStdlibCoroutineSupportApi
import kotlin.coroutines.debug.StackTraceRecoverable
@OptIn(ExperimentalStdlibCoroutineSupportApi::class)
class FileEditException
// 该实现需要一个私有构造函数,
// 以便将 cause 传递给 IllegalStateException 构造函数
private constructor(
val line: Int,
private val detail: String,
cause: Throwable?,
) : IllegalStateException("When editing line $line: $detail", cause),
// 实现 StackTraceRecoverable 以进行堆栈跟踪恢复
StackTraceRecoverable<FileEditException> {
constructor(line: Int, detail: String) : this(line, detail, null)
// 复制行号和消息详情
override fun copyForStackTraceRecovery(): FileEditException =
FileEditException(line, detail, this)
}
fun main() {
val original = FileEditException(15, "Unexpected token")
// 通常情况下,除非您正在测试其行为,否则无需直接调用此函数
// kotlinx.coroutines 库会在堆栈跟踪恢复期间自动调用它
val copy = original.copyForStackTraceRecovery()
println(copy.message)
// When editing line 15: Unexpected token
println(copy.cause == original)
// true
}有关更多信息,请参阅该功能的 KEEP。
欢迎在 YouTrack 中向我们提供反馈。
用于检查集合元素相等性与唯一性的新函数
在 Kotlin 2.4.20 之前,如果您想检查集合元素是否全部互不相同或全部相等,必须使用低效的代码模式。
Kotlin 2.4.20 引入了实验性函数来填补这一空白:
| 函数 | 检查内容 |
|---|---|
allDistinct() | 集合中的每个值都是唯一的。 |
allDistinctBy() | 每个对象在选定属性上都具有唯一的值。 |
allEqual() | 集合中的每个值都是相同的。 |
allEqualBy() | 每个对象在选定属性上都具有相同的值。 |
您可以在集合、序列和数组上使用这些函数。与其他集合操作一样,它们使用结构相等性来比较元素。
这些函数属于实验性 (Experimental),需要使用 @OptIn(ExperimentalStdlibApi::class) 注解或 -opt-in=kotlin.ExperimentalStdlibApi 编译器选项进行选择加入:
@OptIn(ExperimentalStdlibApi::class)
fun main() {
data class Response(
val participantId: String,
val answer: String,
val responseDate: String
)
val responses = listOf(
Response("P001", "Yes", "2026-07-21"),
Response("P002", "Maybe", "2026-07-21"),
Response("P003", "No", "2026-07-21")
)
// 检查是否所有参与者都给出了相同的答案
println(responses.allEqualBy { it.answer })
// false
// 检查是否有重复的参与者
println(responses.allDistinctBy { it.participantId })
// true
// 检查是否所有回答都在同一日期提交
println(responses.allEqualBy { it.responseDate })
// true
val answers = responses.map { it.answer }
// 检查答案是否完全相同
println(answers.allEqual())
// false
// 检查答案是否互不相同
println(answers.allDistinct())
// true
}欢迎在 KEEP 中向我们提供反馈。
用于 `kotlin.test` 断言函数的新重载
Kotlin 2.4.20 为 kotlin.test 断言函数添加了新的重载。它们接受一个 lambda,该 lambda 仅在断言失败时惰性生成错误消息。
此前,像 assertTrue() 或 assertEquals() 这样的 kotlin.test 断言函数仅接受预先格式化的错误消息,这些消息会在每次断言时构建,即使断言成功且该消息实际上从未被使用也是如此。
新的重载使 kotlin.test API 与 JUnit 5 保持一致,接受通过 lambda 提供的消息提供程序,而不是普通字符串。这提升了性能,特别是对于为断言生成详细错误消息的 Power-assert 编译器插件。
以下断言函数提供了新的重载:
| 函数 | 说明 |
|---|---|
assertTrue() / assertFalse() | 检查值是否为 true 或 false。 |
assertEquals() / assertNotEquals() | 检查值是否相等。 |
assertSame() / assertNotSame() | 检查值是否引用同一实例。 |
assertIs() / assertIsNot() | 检查值是否属于指定类型。对于 assertIs(),该函数会将其智能转换为该类型。 |
assertNull() | 检查值是否为 null。 |
assertContains() | 检查元素(键、字符、子字符串或正则表达式)是否存在于集合、数组、序列、区间或映射中。 |
assertContentEquals() | 检查集合、序列或数组是否按相同顺序包含相等的元素。 |
要使用新 API,请通过 @OptIn(ExperimentalKotlinTestApi::class) 注解显式选择加入:
import kotlin.test.ExperimentalKotlinTestApi
import kotlin.test.assertEquals
import kotlin.test.assertTrue
@OptIn(ExperimentalKotlinTestApi::class)
fun testValues(actual: Int, expected: Int, items: List<String>) {
// 仅在断言失败时才会构建消息
assertTrue(actual > 0) { "Expected a positive value but got $actual" }
// 避免格式化列表,除非断言失败
assertEquals(expected, actual) { "Unexpected value for items: ${items.joinToString()}" }
}有关更多信息,请参阅该功能的 KEEP。
Kotlin/Native
Kotlin 2.4.20 为 Kotlin Multiplatform 项目中的 SwiftPM 依赖项带来了自动生成 Package.swift 文件的功能,提供了新的 Swift 导出功能(包括对密封类和跨语言继承的支持),并改进了增量编译。
为 SwiftPM 依赖生成的 Package.swift
当导出依赖于 SwiftPM 软件包的 XCFramework 时,您必须发布生成的 SwiftPM 软件包以便其正确解析。为了解决这一问题,assembleSharedXCFramework Gradle 任务现在会生成一个与 XCFramework 一同分发的 Package.swift 文件。
有关详细信息,请参阅 SwiftPM 导出页面。
新增 Swift 导出功能
密封类
Kotlin 2.4.20 为 Swift 导出添加了对密封类和密封接口的支持。
此前,针对密封类型的每个 switch 语句,您都必须编写一个 default 分支。现在,Kotlin 中定义的密封层次结构会映射到 Swift 枚举,从而在 Xcode 中实现具有完整自动补全的穷举式 switch 语句。
Swift 导出会在每个密封类型上生成一个 sealedType() 方法。该方法返回一个 Swift 枚举,其枚举成员与密封层次结构的直接子类相匹配。您可以嵌套这些调用以匹配更深层次的结构。
例如,在 Kotlin 中声明一个包含类层次结构的密封接口:
// Kotlin
sealed interface Shape
class Circle : Shape {
override fun toString(): String = "Circle"
}
class Rectangle : Shape {
override fun toString(): String = "Rectangle"
}
fun createCircle(): Shape = Circle()在 Swift 端,您可以使用无需 default 分支的穷举式 switch:
// Swift
let shape = createCircle()
let name = switch shape.sealedType() {
case let .circle(type): "It's a \(type.value)"
case let .rectangle(type): "It's a \(type.value)"
}
// name == "It's a Circle"由于 switch 是穷举式的,因此如果向密封层次结构中添加了新的子类,编译器会发出警告,以便您可以立即处理它,而不必依赖 default 分支。
Swift 导出中的跨语言继承
Kotlin 2.4.20 在 Swift 导出中引入了跨语言继承支持。
该功能的一个常见用例是反向导入 (reverse import) 模式,即在 Kotlin 中定义契约,并在 Swift 端提供平台特定的实现。当您需要使用无法直接导入到 Kotlin 中的纯 Swift 库时,这尤其有用。
要实现此模式,请声明一个供 Swift 实现继承的 Kotlin 超类以及一个 Kotlin 接口。然后在 Swift 中实现此接口,并将 Swift 对象传递给接受该接口的 Kotlin 函数。以 CryptoKit 库为例:
在 Kotlin 端,声明一个接口、一个接受该接口的函数以及一个
open基类:kotlin// Kotlin interface CryptoProvider { fun hashMD5(input: String): String } fun processHash(provider: CryptoProvider, input: String): String = provider.hashMD5(input) open class SwiftBase在 Swift 端,继承导出的
SwiftBase类,使用纯 Swift 库实现该接口,并将对象传回 Kotlin:swift// Swift import CryptoKit final class IosCryptoProvider: SwiftBase, CryptoProvider { func hashMD5(input: String) -> String { guard let data = input.data(using: .utf8) else { return "failed" } return Insecure.MD5.hash(data: data).description } } let provider = IosCryptoProvider() // 调用 Kotlin 函数,该函数会回调 Swift 中的 hashMD5() print(processHash(provider: provider, input: "Hello, world!"))
当 Kotlin 接收到一个 Swift 对象时,会将其视为常规接口的实现,直接调用 Swift 代码。
有关 Swift 导出的更多详细信息,请参阅我们的文档。
改进 `klib` 工件的增量编译
Kotlin 2.4.20 对 klib 工件的增量编译进行了稳定性改进,该功能现已进入 Beta 阶段。
此优化最初在 Kotlin 1.9.20 中引入,并被证明可以大幅减少调试构建的编译时间。自那时起,我们修复了许多错误并提升了性能。
要试用增量编译,请将以下选项添加到您的 gradle.properties 文件中:
kotlin.incremental.native=true我们正在积极收集反馈,并计划在后续的 Kotlin 版本中为所有项目默认启用增量编译。如果您遇到任何问题,请向我们的问题跟踪器报告。
Kotlin/Wasm
Kotlin 2.4.20 更改了 Kotlin/Wasm 处理 @JsFun 声明中顶层 require() 调用的方式,使伴生对象初始化顺序与 JVM 行为保持一致,缩减了函数式接口的二进制大小,引入了新的编译模式,并增加了在 Kotlin Gradle 插件中对 Wasmtime 作为 wasmWasi 目标运行时的支持。
@JsFun 声明中顶层 require() 调用的变更
当 @JsFun 声明使用顶层 require() 函数时,Kotlin/Wasm 现在会报告错误。
此前,编译器会在 import-object.mjs 文件中生成一个 require 变量,允许 @JsFun 声明调用 require()。
这种行为无意中暴露了编译器的实现细节。为了支持告别这种做法的迁移,Kotlin/Wasm 移除了这个生成的 require 声明,编译器现在会对这类调用报告错误。例如:
// 报告错误
@JsFun("(mod) => require(mod)")
external fun loadModule(mod: String): JsAny为了应对这一变更,请将 @JsFun 声明中的顶层 require() 调用替换为 @JsModule 注解:
@JsModule("module")
external val module: Module
external interface Module {
// 定义预期的模块成员
}对于动态模块加载,请改用 import() 表达式。 添加 /* webpackIgnore: true */ 魔法注释以防止 webpack 解析动态导入:
@JsFun("""
((module) => () => module)(
await import(/* webpackIgnore: true */ "module")
)
""")
private external fun loadModuleDynamically(): JsAny?您还可以有条件地使用 import() 表达式。例如,您可以仅在 Node.js 中运行时才加载模块:
@JsFun("""
((module) => () => module)(
((typeof process !== "undefined") && (process.release.name === "node"))
? await import(/* webpackIgnore: true */ "module")
: null
)
""")
private external fun loadNodeModule(): JsAny?如果您的项目依赖于需要顶层 require() 函数的依赖项,可以将其添加为 globalThis 的属性作为临时融通方案:
@JsFun("""
((module) => {
globalThis.require = module.default.createRequire(import.meta.url)
return () => {}
})(await import("node:module"))
""")
external fun defineRequire()如果您遇到任何问题,请在我们的问题跟踪器中分享您的反馈。
改进伴生对象初始化顺序
Kotlin/Wasm 现在会在子类伴生对象之前初始化超类伴生对象,与 JVM 行为保持一致。 此前,初始化顺序可能会颠倒,导致跨平台行为不一致。
此更新提高了跨平台一致性,并减少了类初始化行为中平台特定的差异。 它还能正确处理更深继承层次结构中的伴生对象初始化,包括中间类未声明伴生对象的情况。
Kotlin Gradle 插件支持 Wasmtime
Kotlin 2.4.20 在 Kotlin Gradle 插件中引入了对 Wasmtime 作为 wasmWasi 目标运行时的支持。
此前,wasmWasi 目标仅支持 Node.js 运行时,需要 JavaScript 引导程序才能运行 WASI 应用程序。借助 Wasmtime 支持,您现在可以在独立的 WebAssembly 运行时上运行 Kotlin/Wasm 应用程序。
要使用 Wasmtime 作为 wasmWasi 目标的运行时,请将 wasmtime() 添加到您的 Gradle 构建文件中:
kotlin {
wasmWasi {
wasmtime()
}
}欢迎在 YouTrack 中向我们提供反馈。
新增编译模式
Kotlin 2.4.20 增加了对选择 Kotlin/Wasm 编译模式的支持,包括新的多模块模式。此前,编译器采用单体 (monolith) 编译模式,即将项目及其依赖项一起编译并生成单个二进制文件。这使编译器能够执行无效代码消除并生成最小的输出。
您现在可以选择以下编译模式之一:
| 编译模式 | 编译行为 | 输出 | 优化行为 |
|---|---|---|---|
monolith(默认) | 将项目及其依赖项一起编译。 | 单个二进制文件 | 移除无法访问的代码声明,并对整个程序(包括依赖项)应用优化。 |
multimodule-open-world | 独立编译每个模块,且仅重新编译发生更改的模块。 | 每个模块对应一个单独且独立的二进制文件 | 不应用跨模块优化,这会导致二进制文件体积更大。 |
multimodule-closed-world | 在一次调用中处理所有模块,且仅重新编译发生更改的模块。 | 互相依赖的独立二进制文件 | 移除无法访问的代码声明,但对每个 Wasm 二进制文件进行独立优化。 |
要选择编译模式,请将 kotlin.wasm.compilationMode 属性添加到您的 gradle.properties 文件中:
kotlin.wasm.compilationMode=multimodule-open-world您还可以将 Kotlin/Wasm 配置为在开发构建中使用封闭世界多模块编译,而在生产构建中使用单体编译。这可以减少开发期间的重新编译时间,并为生产构建生成最小的输出。
要使用此配置,请将以下属性添加到您的 gradle.properties 文件中:
kotlin.wasm.compilationMode=multimodule-closed-world-only-in-dev欢迎在 YouTrack 中向我们提供反馈。
缩减 lambda 和函数式接口的二进制大小
Kotlin 2.4.20 更改了 Kotlin/Wasm 编译 lambda 和函数式接口的方式。 编译器不再生成单独的匿名类,而是生成函数并使用共享的基类。
针对 KotlinConf 应用程序的测试表明,此更改将 Wasm 二进制大小减少了约 5–10%。
由于此更改引入了更多动态调用,可能会对运行时性能产生影响。 如果您遇到任何问题,请在我们的问题跟踪器中进行报告。
Kotlin/JS
Kotlin 2.4.20 改进了数据类的可导出性,引入了用于浏览器测试的新实验性 DSL,并增加了对将挂起 lambda 导出为 JavaScript async 函数的支持。
导出数据类上合成函数的导出一致性
Kotlin 2.4.20 修复了一个导致 @JsExport.Ignore 注解无法正确应用于数据类属性的问题。
此前,当您使用 @JsExport 注解标记数据类时,由于自动生成的 copy() 和 componentN() 函数,编译器仍会报告关于数据类可导出性的警告。即使构造函数和属性已被显式标记为带有 @JsExport.Ignore 忽略,也会发生这种情况。
例如,考虑一个导出到 JavaScript 的 Session 数据类,它还引用了一个不应导出的内部 DatabaseConnection 类型:
// Kotlin
// 不导出到 JavaScript 的内部类型
class DatabaseConnection
@JsExport
data class Session @JsExport.Ignore constructor(
val userId: String,
@JsExport.Ignore val connection: DatabaseConnection,
)现在该问题已修复,编译器会考虑 @JsExport.Ignore 注解,因此 Session 的合成 copy() 和 componentN() 函数不再触发有关未导出类型 DatabaseConnection 的警告。这与 @ConsistentCopyVisibility 和 @ExposedCopyVisibility 注解引入的可见性规则保持一致。
用于浏览器测试的新 DSL
Kotlin 2.4.20 引入了一个新的实验性 DSL,用于在浏览器环境中运行 Kotlin/JS 测试。
目前,Kotlin Gradle 插件使用 Karma 作为浏览器启动器以在不同浏览器中运行 JavaScript 测试。Karma 项目已停更两年,这促使我们探索支持浏览器测试的替代方式。
新的 DSL 旨在替代 Karma 作为底层不同工具的管理器,它包括:
- Playwright 作为浏览器驱动器和分发管理器,支持 Chromium、Firefox 和 WebKit (Safari) 浏览器引擎。
- Mocha 作为测试运行程序。
- webpack 作为打包器(将在未来版本中替换为 Vite)。
要试用用于浏览器测试的新 DSL,请为您 Kotlin/JS 目标中的 browser {} 内部添加选择加入的 test {} 块:
import org.jetbrains.kotlin.gradle.ExperimentalJsTestDsl
import kotlin.time.Duration.Companion.seconds
kotlin {
js {
browser {
// 添加并配置新的 test {} 块
@OptIn(ExperimentalJsTestDsl::class)
test {
// 为所有运行器配置默认超时
timeout = 2.seconds
// 使用 Gradle provider 配置无头模式
headless = providers
.environmentVariable("IS_IN_CI")
.map { it.toBoolean() }
.orElse(false)
// 启用并配置 Chromium 测试运行程序
chromium {
// 覆盖常规超时选项
timeout = 5.seconds
// 添加额外启动实参
launchArgs.add("--no-sandbox")
}
// 启用 Firefox 测试运行程序
firefox()
// 启用 WebKit 测试运行程序
webkit()
// 启用并配置额外的 WebKit 测试运行程序
webkit("noheadless") {
// 设置自定义选项
headless = false
}
}
}
}
}用于浏览器测试的新 DSL 正在积极开发中。欢迎在 YouTrack 中向我们提供反馈。
有关更多信息,请参阅在 Kotlin/JS 中运行测试。
支持将挂起 lambda 导出为 async 函数
在 Kotlin 2.4.20 中,您现在可以将挂起 lambda 表达式导出为 JavaScript async 函数。
此前,无法从 Kotlin/JS 库中导出包含挂起 lambda 的声明。现在,Kotlin 编译器会自动处理 Kotlin 的 suspend 函数与 JavaScript 原生 async/await 模型之间的桥接,这对于 Kotlin/TypeScript 混合代码库非常有用。
要启用此功能,请将以下编译器选项添加到您的 build.gradle.kts 文件中:
kotlin {
js {
compilations.all {
compileTaskProvider.configure {
compilerOptions {
freeCompilerArgs.add("-Xsuspend-lambda-exporting")
}
}
}
}
}然后,使用 @JsExport 标记相关声明:
// Kotlin
@JsExport
class TaskRunner {
suspend fun runTask(task: suspend () -> String): String {
return task()
}
}在 TypeScript 端,挂起 lambda 将表现为常规 async 函数:
// TypeScript
import { TaskRunner } from "..."
const runner = new TaskRunner();
const result = await runner.runTask(async () => "done");
console.log(result); // "done"有关 @JsExport 注解的更多信息,请参阅我们的文档。
Gradle
Kotlin 2.4.20 完全兼容 Gradle 7.6.3 至 9.7.0。您也可以使用最新的 Gradle 发行版本。但请注意,这样做可能会导致弃用警告,并且某些新的 Gradle 功能可能无法正常工作。
Kotlin 2.4.20 还改进了与 Problems API 的集成。
改进 Problems API 中的报告
Kotlin 2.2.0 是首个实现 Kotlin Gradle 插件 (KGP) 与 Gradle 的 Problems API 集成的版本。 Kotlin 2.4.0 增加了对针对 Kotlin/JVM 将编译器消息写入 Problems API 的支持。
Kotlin 2.4.20 在编译器传递给 Problems API 的信息中添加了编译器诊断 ID。 它还按这些 ID 对诊断信息进行分组,从而更容易识别编译问题的根源。
从 Gradle 8.6 开始,KGP 默认启用此集成。由于该 API 仍在演进中,建议使用最新的 Gradle 版本以体验最新改进。
构建工具 API
Kotlin 2.4.20 为构建工具 API 添加了对 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据的实验性支持。
支持 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据
在 Kotlin 2.2.0 中,构建工具 API (BTA) 开始支持 Kotlin/JVM。Kotlin 2.4.20 通过添加对新目标(Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据)的支持,朝着 BTA 稳定化迈出了下一步。
这使得 Kotlin Gradle 插件与编译器的交互更加一致。在某些情况下,您还可以受益于更快、更稳定的编译。
BTA 是一个通用 API,充当构建系统与 Kotlin 编译器生态系统之间的抽象层。 它有助于在现有的构建工具中支持 Kotlin 功能以及保持与 Kotlin 编译器的兼容性。
在 Kotlin 2.4.20 中,新目标的 BTA 作为可选择加入的功能提供。要进行试用,请将相应属性添加到您的 gradle.properties 文件中:
kotlin.wasm.runViaBuildToolsApi=true
kotlin.js.runViaBuildToolsApi=true
kotlin.metadata.runViaBuildToolsApi=true从 Kotlin 2.5.0 开始,我们计划在 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据中默认启用 BTA。
如果您对 BTA 提案感兴趣或想分享您的反馈,请参阅此 KEEP。
Kotlin 编译器
Kotlin 2.4.20 包含关于将 Kotlin 运行器命令变更为 kotlinr 的更新,并引入了实验性的 Kotlin 编译器原生镜像。
将 Kotlin 运行器命令从 kotlin 更改为 kotlinr
kotlinr 命令取代了 kotlin 作为 Kotlin 运行器命令,以避免与 Kotlin 工具链 (Kotlin Toolchain) 中的 kotlin 命令发生命名冲突。当您使用 kotlin 命令时,Kotlin 运行器还会向您发出警告并建议改用 kotlinr。
原生镜像
Kotlin 2.4.20 带来了 Kotlin 编译器原生镜像的首个实验性 (Experimental)版本。该原生镜像可直接替代标准的 kotlinc 命令行工具,同时提供更快的启动时间和更高的性能。
要试用原生镜像,请从 GitHub Releases 下载构建。
原生镜像还捆绑了以下编译器插件,您可以通过 -Xplugin 或 -Xcompiler-plugin 命令行选项来使用它们:
有关 Kotlin 编译器原生镜像的更多信息,请参阅其 README。
破坏性变更与弃用
本节重点介绍重要的破坏性变更和弃用。有关完整概述,请参阅我们的兼容性指南。
- 由于 Apple 正在放弃对其 32 位 watchOS 目标的支持,因此
watchosArm32Kotlin/Native 目标现已弃用。计划在 Kotlin 2.5.0 中将其移除,以确保与 Xcode 27 兼容。 - 从 Kotlin 2.4.20 开始,Kotlin/Native 编译器禁止在
public内联函数内部或从另一个文件调用的internal内联函数内部使用 AtomicFU 原子操作。 - Kotlin 2.4.20 将 webpack 的 npm 依赖项更新为 5.108.1。这可能会在两个方面影响您的项目:
- webpack 已将其内置的代码压缩器 (minimizer) 依赖项从
terser-webpack-plugin迁移到适用范围更广的minimizer-webpack-plugin。Terser 仍是默认的 JavaScript 压缩器,但如果您的项目直接配置或依赖于terser-webpack-plugin,可能需要更新其配置。 - webpack 在确定 JavaScript 文件的模块类型时不再忽略
import.meta。如果存在import.meta,webpack 会将该文件视为 ES 模块,这可能会破坏同时使用 CommonJS 结构的文件。对于 Kotlin/JS,您可以使用useEsModules()Gradle DSL 配置目标以使用 ES 模块。在大多数情况下,Kotlin/Wasm 无需额外配置即可正常工作。如果在 Kotlin/Wasm 中遇到import.meta错误,请检查项目的源代码或直接/传递依赖项是否使用了import.meta。根据需要更新您自己的代码。如果是由依赖项引起的问题,请将其更新到兼容版本(如果有),或者向该库的维护者报告问题。
- webpack 已将其内置的代码压缩器 (minimizer) 依赖项从
- 从 Kotlin 2.4.20 开始,Kotlin/Wasm 弃用了生成的 JavaScript
wasmExportsAPI。编译器禁止访问除wasmExports.memory之外的所有导出项,而wasmExports.memory暂时可用并会伴有警告。请使用kotlin.wasm.unsafe.wasmMemory属性访问模块的WebAssembly.Memory对象。
文档更新
自上一版本以来,我们为 Kotlin 生态系统文档创建了新的页面和教程,并对现有内容进行了翻新:
- 配置 iOS 交付流水线 – 使用 TeamCity 为 Kotlin Multiplatform iOS 应用设置持续交付。
- Compose Multiplatform 更新:
- 弹出窗口 (Popups) – 了解如何在 Compose Multiplatform 中创建和配置弹出窗口。
- 窗口与对话框 API v2 – 探索在 Compose Multiplatform 中管理桌面窗口和对话框的新 API。
- 托盘与通知 – 了解如何在 Compose Multiplatform 桌面端中将应用程序图标添加到系统托盘并发送系统通知。
- 菜单栏 – 了解如何在 Compose Multiplatform 桌面端中为特定窗口创建菜单栏。
- 拖放 (Drag and drop) – 了解在 Compose Multiplatform 中实现拖放时如何处理平台特定数据。
- 面向 Liquid Glass 的 UIKit 替代方案 – 探索 Liquid Glass 的替代方法:跳过 SwiftUI 并从 Kotlin 驱动 UIKit 导航。
- 适用于 AI Agent 的 MCP 服务器 – 了解如何使用 Compose Hot Reload 中的 MCP 服务器将 AI Agent 连接到您的开发工作流。
- 使用 Spring 进行缓存 – 学习带有全新 Kotlin 示例的 Spring 应用程序缓存添加教程。
- Exposed IntelliJ IDEA 插件 – 了解如何在 IntelliJ IDEA 中结合代码补全、数据库感知检查和实时模板来使用 Exposed。
- Kotlin 序列化 (Serialization) – 了解如何序列化 Kotlin 数据、自定义 JSON 结构与类型表示,以及处理更高级的序列化场景。
- Flow 与 Flow 运算符 – 了解如何创建和收集冷流与热流、处理异常,以及使用各种 Flow 运算符。
- 调试协程 – 了解如何使用调试模式、堆栈跟踪恢复和调试代理在 JVM 上调试协程。
- Lincheck – 了解 Lincheck 中模型检查 (model checking) 的工作原理、如何使用操作执行选项,以及如何验证测试结果。
- kapt 编译器插件 – 了解如何在 Gradle、Maven 和命令行编译器中配置 kapt 编译器插件。
- Kotlin 项目中的代码质量工具 – 探索用于分析 JVM 字节码和 Kotlin 代码的工具。
- 结合 Maven 使用 Power-assert 插件 – 了解如何使用 Power-assert 插件获取更详细的测试失败消息。
- 使用 KSP 进行多轮处理 – 探索 KSP 如何跨多个处理轮次工作,包括生成的文件、推迟的符号和验证。
- 不可指称类型 (Non-denotable types) – 了解 Kotlin 中的平台类型、捕获类型和交叉类型。
- 类型别名 – 了解类型别名的作用域和可见性。
- This 表达式 – 了解隐式
this的解析方式,以及何时显式使用this来引用接收者。 - 字符串 – 了解字符串模板、常用字符串操作、构建字符串以及类型转换。
- 软件包和导入 – 了解如何使用包和导入组织 Kotlin 代码。
