用途
本技能用于将 Kotlin Multiplatform (KMP) 项目从 CocoaPods 迁移到 Swift Package Manager。迁移的核心是把项目中的 kotlin("native.cocoapods") 配置改为 swiftPMDependencies {} DSL，并使用 swiftPackage() 替换原有的 pod() 声明。
前置要求
- Kotlin：2.4.0-Beta2 或更高版本（首个公开支持 swiftPMDependencies 的版本，可从 Maven Central 获取）
- Xcode：16.4 或 26.0+
- iOS 部署目标：建议 16.0+
主要能力（迁移阶段）
迁移按阶段推进，关键原则是：在第 6 阶段之前，保留 cocoapods {} 块与插件处于启用状态。先新增 swiftPMDependencies {}、重新配置 Xcode，最后才移除 CocoaPods。
- 阶段 1：分析现有 CocoaPods 配置，包括查找使用 CocoaPods 的模块、提取 pod 依赖与版本、记录框架配置（baseName、isStatic、部署目标）、记录 linkOnly 的 pod、查找 Kotlin 导入、定位 iOS 项目目录、检查非 KMP 的 CocoaPods、比对 Podfile 与 cocoapods {} 块、检查 Xcode 构建阶段、检查 Crashlytics dSYM 上传脚本、识别构建脚本中的 CocoaPods 相关附加内容。
- 阶段 2：更新 Gradle 配置（仓库、Kotlin 版本）。
- 阶段 3：在保留 cocoapods {} 的同时新增 swiftPMDependencies {}。
- 阶段 4：转换 Kotlin 导入。
- 阶段 5：重新配置 iOS 项目并 deintegrate CocoaPods。
- 阶段 6：从 Gradle 中移除 CocoaPods 插件。
- 阶段 7：验证 Gradle 构建与 Xcode 项目构建。
- 阶段 8：编写 MIGRATION_REPORT.md。
使用方式（要点摘录）
- 查找使用 CocoaPods 的模块： grep -rl "cocoapods" --include="build.gradle.kts" .
- 验证 Kotlin 编译： ./gradlew :moduleName:compileKotlinIosSimulatorArm64
- 构建 iOS 应用（可选，查找工程）： find . -name ".xcworkspace" -not -path "/Pods/*" -maxdepth 2
- 新增 swiftPMDependencies 示例： swiftPackage(url = "https://github.com/owner/repo.git", version = "1.0.0", products = listOf("ProductName"))
- 需要 @ExperimentalKotlinGradlePluginApi 的 opt-in。
适用场景
适用于准备将 iOS 端依赖从 CocoaPods 切换到 SwiftPM 的 KMP 项目，包括使用 dev.gitlive/firebase-kotlin-sdk 等 CocoaPods 时代 KMP 封装库的项目，以及对 Xcode 工程、embedAndSign、Crashlytics dSYM 脚本有定制配置的项目。
限制与注意事项
- 迁移期间不要升级 Gradle wrapper、KSP 或其他依赖，也不要提升依赖版本。
- 不要把同一个库套件混用 CocoaPods 与 SPM，否则会出现重复符号或运行时 dyld 崩溃。
- 使用 Compose Multiplatform 资源时，group 属性同时用于生成资源访问器命名空间，首次添加 group 需提醒用户相关调用点可能需更新。
- 需要维护 MIGRATION_REPORT.md 记录迁移结果。
- 该资料未提供 8000 字级别的完整细节（如常见 pod 到 SPM 的完整映射表、typed API 完整说明），这些属于后续文档内容，此处暂未提供。