可放心加到 commonMain 的 KMP 兼容库包括：kotlinx-coroutines-core、ktor-client-core、reaktive 等明确支持多平台的库；需避免 Android/JVM 专属依赖，且必须在 kotlin.sourceSets.commonMain.dependencies 块中声明。
直接在 commonMain 的 dependencies 块里声明，但必须确保依赖本身是 multiplatform 兼容的——否则编译会失败或只在部分平台生效。
哪些库能放心加到 commonMain？
只有明确标注支持 Kotlin Multiplatform（KMP）的库才适合。常见可靠选择包括：
-
kotlinx.coroutines（需用kotlinx-coroutines-core，不是kotlinx-coroutines-android） -
kotlin.test（仅限commonTest，commonMain不要加） -
ktor-client-core（不是ktor-client-android或ktor-client-jvm） -
reaktive系列（如com.badoo.reaktive:reaktive） - 你自己写的、未引用任何平台 API 的纯 Kotlin 模块
错误示例：implementation "androidx.core:core-ktx:1.12.0" —— 这个库只针对 Android，加进 commonMain 会导致 iOS/macOS/JVM 编译失败。
build.gradle.kts 中的正确写法
必须在 kotlin { sourceSets { commonMain { dependencies { ... } } } } 结构内声明，不能放在顶层 dependencies 块里。示例：
kotlin {
sourceSets {
commonMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
implementation("io.ktor:ktor-client-core:2.3.12")
implementation("com.badoo.reaktive:reaktive:3.1.0")
}
}
}
注意：如果你用了 libs.versions.toml（推荐），应通过 libs.kotlinx.coroutines.core 这类别名引用，而非硬编码字符串。
为什么有时加了却没生效？
常见原因有三个：
- 依赖的 transitive 依赖里偷偷引入了平台专属类（比如某个库内部
expect了android.os.Looper），导致 JVM/iOS 编译报错 —— 此时要查它的build.gradle.kts或 Maven POM，确认是否真为 multiplatform 发布 - 你加到了
commonMain，但某个平台源集（如androidMain）又重复加了同名但不同版本的实现，引发冲突 —— KMP 不允许这种“覆盖”，Gradle 会静默丢弃或报Could not resolve - IDE 缓存未刷新：改完后必须执行
./gradlew --refresh-dependencies或点击 Android Studio 的 “Refresh project” 按钮，否则代码补全和编译都看不到新加的 API
最容易被忽略的一点：KMP 的 commonMain 本质是“契约层”，它不打包任何具体实现。所有实际逻辑最终由各平台源集提供。所以即使你成功加了一个 multiplatform 库，也得确认它在目标平台（如 iOS）上确实提供了 actual 实现，否则运行时会抛 UninitializedPropertyAccessException 或链接失败。
