使用 Swift export 与 Swift 互操作

Kotlin 能够通过 Swift export 与 Swift 互操作, 这个功能目前处于 Alpha 阶段. Swift export 能够直接导出 Kotlin 源代码, 并以符合 Swift 习惯的方式, 从 Swift 调用 Kotlin 代码, 因此不需要 Objective-C 头文件.

Swift export 使针对 Apple 目标平台的跨平台开发更加流畅. 例如, 如果你有一个包含顶层函数的 Kotlin 模块, Swift export 可以实现简洁的, 特定于模块的导入, 消除令人困惑的 Objective-C 下划线和混淆的名称.

Swift export 当前的功能包括:

多模块支持. 每个 Kotlin 模块作为独立的 Swift 模块导出, 简化了函数调用.
包支持. 在导出期间明确的保留 Kotlin 包, 避免在生成的 Swift 代码中发生命名冲突.
类型别名. Kotlin 类型别名在导出时会保留在 Swift 中, 提高可读性.
对于基本类型, 增强可空性. 与 Objective-C 的互操作, 需要将 Int? 等类型装箱为 KotlinInt 之类的包装类, 来保留可空性, 与此不同, Swift export 能够直接转换可空性信息.
重载. 你可以在 Swift 中调用 Kotlin 的重载函数, 不会发生歧义.
扁平化的包结构. 你可以将 Kotlin 包转换为 Swift 枚举, 在生成的 Swift 代码中删除包前缀.
自定义模块名称. 你可以在 Kotlin 项目的 Gradle 配置中, 自定义生成的 Swift 模块名称.
并发支持. 你可以从 Swift 无缝的调用 Kotlin 的挂起代码, 并直接将 kotlinx.coroutines 流(Flow)导出为 Swift 的 AsyncSequence.

启用 Swift export

Swift export 目前处于 Alpha 阶段, 还不完整, 因此预计会有破坏性变更. 要试用这个功能, 请在你的 Kotlin 项目中配置构建文件, 并设置 Xcode 集成 Swift export.

配置 Kotlin 项目

你可以在项目中使用以下构建文件, 作为设置 Swift export 的起点:

// build.gradle.kts
kotlin {

    iosArm64()
    iosSimulatorArm64()

    swiftExport {
        // 设置根模块名称
        moduleName = "Shared"

        // 设置折叠规则
        // 在生成的 Swift 代码中删除包前缀
        flattenPackage = "com.example.sandbox"

        // 配置外部模块的导出
        export(project(":subproject")) {
            // 设置导出的模块名称
            moduleName = "Subproject"
            // 对导出的依赖项, 设置折叠规则
            flattenPackage = "com.subproject.library"
        }

        // 为链接任务提供编译器参数
        configure {
            freeCompilerArgs.add("-Xexpect-actual-classes")
        }
    }
}

Kotlin 编译器会自动生成所有需要的文件 (包括 swiftmodule 文件, .a 静态库, 头文件, 以及 modulemap 文件), 并将它们复制到应用程序的构建目录中, 你可以从 Xcode 访问这些文件.

配置 Xcode 项目

配置 Xcode, 将 Swift export 集成到你的项目中, 方法如下:

在 Xcode 中, 打开项目设置.
在 Build Phases 页上, 找到包含 embedAndSignAppleFrameworkForXcode 任务的 Run Script 阶段.
在 Run Script 阶段中, 将脚本替换为 embedSwiftExportForXcode 任务:
./gradlew :<Shared module name>:embedSwiftExportForXcode
构建项目. 构建会在输出目录中生成 Swift 模块.

当前的限制

Swift export 目前只能用于使用直接集成将 iOS 框架连接到 Xcode 项目的项目. 这是通过 IntelliJ IDEA 中的 Kotlin Multiplatform plugin 创建的, 或通过 Web 向导创建的 Kotlin Multiplatform 项目的标准配置.

其他已知的问题包括:

继承自 List, Set 或 Map 的类型, 在导出时会被忽略 (KT-80416).
List, Set 或 Map 的继承者, 在 Swift 端无法实例化 (KT-80417).
导出到 Swift 时, Kotlin 泛型类型参数会被类型擦除, 变成它的上界类型.
不支持跨语言继承, 因此 Swift 类不能直接继承 Kotlin 导出的类或接口.
没有可用的 IDE 迁移提示或自动化工具.
使用需要使用者同意(Opt-in)的声明时, 你必须在 Gradle 构建文件的模块级别添加明确的 optIn 编译器选项. 例如, 对于 kotlinx.datetime 库:
swiftExport { moduleName = "Shared" export("org.jetbrains.kotlinx:kotlinx-datetime:0.8.0") { moduleName = "KotlinDateTime" flattenPackage = "kotlinx.datetime" } } // 在模块级别添加单独的 opt-in 代码块 compilerOptions { optIn.add("kotlin.time.ExperimentalTime") }

映射关系

下表说明 Kotlin 的概念如何映射到 Swift.

Kotlin	Swift
`class`	`class`
`object`	带 `shared` 属性的 `class`
`enum class`	`enum`
`typealias`	`typealias`
函数	Function
`suspend fun`	`async`
`kotlinx.coroutines` 流(Flow)	`AsyncSequence`
属性	Property
构造函数	Initializer
包	Nested enum
`Boolean`	`Bool`
`Char`	`Unicode.UTF16.CodeUnit`
`Byte`	`Int8`
`Short`	`Int16`
`Int`	`Int32`
`Long`	`Int64`
`UByte`	`UInt8`
`UShort`	`UInt16`
`UInt`	`UInt32`
`ULong`	`UInt64`
`Float`	`Float`
`Double`	`Double`
`Any`	`KotlinBase` 类
`Unit`	`Void`
`Nothing`	`Never`

声明

类

Swift export 只支持直接继承自 Any 的 final 类, 例如 class Foo(). 它们会被转换为继承自特殊的 KotlinBase 类的 Swift 类:

// Kotlin
class MyClass {
    val property: Int = 0

    fun method() {}
}

// Swift
public class MyClass : KotlinRuntime.KotlinBase {
    public var property: Swift.Int32 {
        get {
            // ...
        }
    }
    public override init() {
        // ...
    }
    public func method() -> Swift.Void {
        // ...
    }
}

对象

对象会被转换为带有 private init 和 static shared 访问器的 Swift 类:

// Kotlin
object O

// Swift
public class O : KotlinRuntime.KotlinBase {
    public static var shared: O {
        get {
            // ...
        }
    }
    private override init() {
        // ...
    }
}

类型别名

Kotlin 类型别名会原样导出:

// Kotlin
typealias MyInt = Int

// Swift
public typealias MyInt = Swift.Int32

枚举

Kotlin enum class 声明会导出为通常的原生 Swift enum 类型:

// Kotlin
enum class Color(val rgb: Int) {
    RED(0xFF0000),
    GREEN(0x00FF00),
    BLUE(0x0000FF)
}

val color = Color.RED

// Swift
public enum Color: Swift.CaseIterable, Swift.LosslessStringConvertible, Swift.RawRepresentable {
    case RED, GREEN, BLUE

    public var rgb: Swift.Int32 { get }
}

函数

Swift export 支持简单的顶层函数和方法:

// Kotlin
fun foo(a: Short, b: Bar) {}

fun baz(): Long = 0

// Swift
public func foo(a: Swift.Int16, b: Bar) -> Swift.Void {
    // ...
}

public func baz() -> Swift.Int64 {
    // ...
}

对于 Kotlin 的扩展函数, 接收者参数会成为 Swift 中位于第一个的普通参数:

// Kotlin
fun Int.foo(): Unit = TODO()

// Swift
func foo(_ receiver: Int32) {}

Kotlin 带有 vararg 的函数, 会映射到 Swift 的可变参数函数:

// Kotlin
fun log(vararg messages: String)

// Swift
public func log(messages: Swift.String...)

属性

Kotlin 属性会被转换为 Swift 属性:

// Kotlin
val a: Int = 0

var b: Short = 15

const val c: Int = 0

// Swift
public var a: Swift.Int32 {
    get {
        // ...
    }
}
public var b: Swift.Int16 {
    get {
        // ...
    }
    set {
        // ...
    }
}
public var c: Swift.Int32 {
    get {
        // ...
    }
}

构造函数

构造函数会被转换为 Swift 初始化器:

// Kotlin
class Foo(val prop: Int)

// Swift
public class Foo : KotlinRuntime.KotlinBase {
    public init(
        prop: Swift.Int32
    ) {
        // ...
    }
}

类型

kotlin.Nothing

Kotlin 的 Nothing 类型会被转换为 Never 类型:

// Kotlin
fun foo(): Nothing = TODO()

fun baz(input: Nothing) {}

// Swift
public func foo() -> Swift.Never {
    // ...
}

public func baz(input: Swift.Never) -> Void {
    // ...
}

分类器类型(Classifier Type)

Swift export 目前只支持直接继承自 Any 的 final 类.

包

Kotlin 包会被转换为嵌套的 Swift 枚举, 以避免命名冲突:

// Kotlin
// foo.bar 包中的 bar.kt 文件
fun callMeMaybe() {}

// Kotlin
// foo.baz 包中的 baz.kt 文件
fun callMeMaybe() {}

// Swift
public extension foo.bar {
    public func callMeMaybe() {}
}

public extension foo.baz {
    public func callMeMaybe() {}
}

public enum foo {
    public enum bar {}

    public enum baz {}
}

并发

挂起函数

你可以从 Swift 调用 Kotlin 的挂起代码. Kotlin 挂起函数和挂起函数类型, 会被导出为 Swift 的 async 函数和函数类型:

// Kotlin
suspend fun hello(): String {
    delay(1000)
    return "Hello Swift! This is Kotlin."
}

// Swift
let msg = try await hello()

流(Flow)

你还可以将 kotlinx.coroutines 流(Flow)导出为 Swift 的 AsyncSequence:

// Kotlin
// 导出 Flow, 保留 String 类型
fun flowOfStrings(): Flow<String> = flowOf("hello", "any", "world")

// Swift
var actual: [String] = []

// 从 Kotlin 推断 String 类型
for try await element in flowOfStrings().asAsyncSequence() {
    actual.append(element)
}

协程派发器(Coroutine Dispatcher)

默认情况下, 当你从 Swift 调用 Kotlin 挂起函数，或使用 asAsyncSequence 函数时, Kotlin 会创建一个协程上下文(Coroutine Context), 它使用 Dispatchers.Default 派发器, 并在这个协程上下文中执行导出的代码.

要在不同的派发器上运行导出的代码, 请在 Kotlin 中使用 withContext() 函数切换协程上下文. 例如:

suspend fun runOnMain(): Int = withContext(Dispatchers.Main) {
    delay(10L)
    42
}

Swift export 的演进

我们计划在未来的 Kotlin 版本中扩展 Swift export 的功能, 并逐步稳定, 改善 Kotlin 和 Swift 之间的互操作性. 你可以在以下地方留下你的反馈意见:

在 Kotlin Slack 中 - 获取邀请, 并加入 #swift-export 频道.
在 YouTrack 中报告问题.

2026/08/12