Kotlin Multiplatform序列化iOS目标编译链接错误求助

问题本质 #

iOS编译时找不到Something.Companion.serializer()符号，说明iOS目标的编译产物里没生成这个序列化方法——Android正常是因为插件和依赖配置生效了，但iOS端没正确触发序列化代码生成。

修复步骤 #

1. 确认序列化插件在所有多平台模块生效

如果项目里有单独的shared模块（从错误路径能看到shared/build），必须在shared/build.gradle.kts里应用序列化插件，仅在composeApp模块应用是不够的：

plugins {
    kotlin("multiplatform")
    id("org.jetbrains.kotlin.plugin.serialization") // 必须添加这行
}

2. 严格匹配Kotlin与序列化依赖版本

序列化插件和kotlinx-serialization-json的版本必须与项目使用的Kotlin版本完全对应，否则会出现兼容性问题。
在libs.versions.toml里确认配置：

kotlin = "2.0.20-Beta2"
kotlinx-serialization-json = "1.7.3" # 此版本适配Kotlin 2.0.x系列，务必确保版本匹配
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

3. 强制编译器保留序列化符号

Kotlin编译器可能因为serializer()方法未被直接调用（比如通过跨平台序列化框架间接调用）而将其优化掉，需要显式保留：

• 方法一：在Something类所在的commonMain文件中添加空引用函数（无需实际调用）：

@Serializable
data class Something(
    val value: Int,
    val otherValue: String,
)

// 强制编译器保留serializer方法
@OptIn(ExperimentalSerializationApi::class)
fun keepSerializer() = Something.serializer()

• 方法二：在iOS目标的Gradle配置中添加链接参数，强制保留符号：

kotlin {
    iosArm64 {
        binaries.framework {
            linkerOpts.add("-Xlinker -u _kfun:utils.Mutations.Something.Companion#serializer(){}kotlinx.serialization.KSerializer<utils.Mutations.Something>")
        }
    }
    iosX64 {
        binaries.framework {
            linkerOpts.add("-Xlinker -u _kfun:utils.Mutations.Something.Companion#serializer(){}kotlinx.serialization.KSerializer<utils.Mutations.Something>")
        }
    }
}

4. 清理缓存并重新构建

执行以下命令彻底清理缓存，避免旧编译产物干扰：

./gradlew clean
./gradlew composeApp:assembleDebug
./gradlew shared:iosFrameworkDebug # 项目有shared模块时执行

之后重新在Xcode中编译iOS项目。

5. 修复Xcode框架引用路径警告

虽然当前警告没直接影响，但解决它能避免潜在问题：手动创建缺失的路径/Users/lancylot2004/Desktop/ActiveApp/shared/build/xcode-frameworks/Debug/iphonesimulator17.5，或者在Xcode的项目设置中更新框架搜索路径，指向正确的输出目录。

内容的提问来源于stack exchange，提问作者lancylot2004