近日，JetBrains 官方宣布 Kotlin Multiplatform（KMP）正式加入对 Swift Package Manager（SwiftPM）的原生支持，这意味着长期以来依赖 CocoaPods 进行 iOS 端依赖管理的 KMP 开发者，终于迎来了官方推荐的迁移方案。此举不仅简化了跨平台项目的构建流程，更标志着 KMP 生态与苹果原生工具链的深度整合迈出了关键一步。

从 CocoaPods 到 SwiftPM：为何必须迁移？

在 KMP 的早期版本中，开发者若要将共享的 Kotlin 模块集成到 iOS 应用，通常需要借助 CocoaPods 插件，通过生成 Podspec 文件来实现依赖注入。这一方案虽然可行，却始终存在性能瓶颈和兼容性问题：CocoaPods 的预编译阶段会拖慢增量构建速度，且在 xcframeworks 格式下，调试符号的传递时常出现错乱。随着苹果逐步将 SwiftPM 设为 Xcode 默认依赖管理工具，CocoaPods 在第三方库支持上的滞后性愈发明显——许多新发布的 Swift 库直接跳过 CocoaPods，仅提供 SwiftPM 版本。

SwiftPM 的优势则非常直观：它内置于 Xcode 之中，无需额外安装工具，支持二进制分发的同时还能精确控制依赖版本，并原生兼容 Xcode 的“自动解析”机制。对于 KMP 项目而言，迁移至 SwiftPM 意味着 iOS 端的依赖解析将不再依赖 Ruby 环境或第三方插件，构建日志更加清晰，CI/CD 配置也更简洁。

官方迁移指南要点解析

根据 JetBrains 发布的配置指南，迁移过程主要涉及三个层面的调整：KMP 插件配置、Xcode 工程设置以及Gradle 构建脚本。

首先，开发需将项目中使用的 KMP CocoaPods 插件替换为新的 SwiftPM 集成插件。Gradle 构建文件中原本的 id("org.jetbrains.kotlin.native.cocoapods") 应改为 id("org.jetbrains.kotlin.multiplatform")，并启用新的 SwiftPM 导出能力。具体配置如下：

kotlin {
    iosX64()
    iosArm64()
    iosSimulatorArm64()

    // 启用 SwiftPM 输出
    binaries {
        framework {
            baseName = "SharedKit"
            isStatic = true
            export(project(":shared"))
        }
    }
}

生成 Framework 后，开发者需要在 Xcode 项目中手动添加本地 Swift Package。打开项目设置，选择“Package Dependencies”，点击“+”并选择“Add Local”，定位至 build/bin/iosArm64/releaseFramework/SharedKit.xcframework 所在的目录。值得注意的是，每次 Gradle 构建后，SwiftPM 依赖的搜索路径可能需要重新索引，官方建议在 Run Script 阶段添加自动刷新命令：

cd $SRCROOT
xcodebuild -resolvePackageDependencies -project YourApp.xcodeproj

潜在风险与最佳实践

尽管迁移流程已大幅简化，但仍有几个常见陷阱值得警惕。首先，多架构整合问题：默认情况下，KMP 会为每个 iOS 目标架构生成独立的 Framework，而 SwiftPM 要求一个包含所有架构的 xcframework。因此，必须在 Gradle 脚本中通过 mergeAll 任务合并所有变种，否则 Xcode 在真机调试时会因缺少 arm64 模拟器切片而报错。

其次，C 语言互操作性：若共享模块中使用到了 KMP 的 @cinterop 特性（如调用 iOS 原生框架），则必须确保生成的 framework 头文件路径正确。在 SwiftPM 中，头文件可能无法被自动识别，需要在 Package.swift 中显式声明 headerSearchPaths。

此外，开发团队还应注意依赖循环问题。当 KMP 模块同时依赖多个 CocoaPods 私有库时，SwiftPM 容易陷入递归解析死锁。官方建议在过渡期内，对未完成迁移的第三方库仍保留 CocoaPods 作为二重依赖，但需通过 unsafeFlags 强制忽略 SwiftPM 自身的版本约束。

未来展望

KMP 正式拥抱 SwiftPM，本质上是 Kotlin 跨平台策略向“原生优先”的进一步靠拢。对于混合团队而言，这一改动降低了 iOS 开发者的学习成本——他们无需再理解 Gradle 或 RubyGem，只需像管理普通 Swift 包一样维护 Kotlin 模块。同时，JetBrains 也表示正在与 Apple 工程师合作，探索将 KMP Framework 直接发布为远程 Swift Package 的可能性，届时跨平台库的共享将真正实现“一键依赖”。

对于正在使用 KMP 的团队，建议在下一个迭代周期中尽快启动迁移测试。虽然过渡期仍需同时维护两套构建方案，但 SwiftPM 带来的编译速度提升和 Xcode 原生兼容性，足以抵消初期调整的时间成本。毕竟，在苹果生态中，拥抱 SwiftPM 已不再是可选项，而是未来开发的基础设施。