把 KMP 项目从 CocoaPods 迁移到 Swift…

当 Kotlin Multiplatform 项目使用 kotlin("native.cocoapods") 且需要改用 swiftPMDependencies DSL 时，按阶段并行添加 SwiftPM、重配 Xcode、再移除 CocoaPods。

适用场景

解决思路

1. 阶段 1 预迁移分析：先用 `grep -rl "cocoapods" --include="build.gradle.kts" .` 找出所有使用 CocoaPods 的模块，记录模块名（可能多个，但通常只有产出 iOS 框架的模块需要 swiftPMDependencies，其他模块只需在阶段 6 移除 CocoaPods）。
2. 阶段 1：运行 `./gradlew :moduleName:compileKotlinIosSimulatorArm64` 验证 Kotlin 代码可编译（比完整 build 快，且足以验证 Kotlin 正确性）；可选地用 `find . -name "*.xcworkspace" -not -path "*/Pods/*" -maxdepth 2` 找到 Xcode 工程并用 `xcodebuild -workspace *.xcworkspace -scheme "<AppScheme>" -destination 'generic/platform=iOS Simulator' ARCHS=arm64` 构建 App。若 Kotlin 编译失败，让用户提供正确的 Gradle 命令或确认模块可用；若用户仅口头确认，记录“迁移前构建未验证”并在阶段 7 警告。
3. 阶段 1.0a：从 `gradle/libs.versions.toml` 或 `build.gradle.kts` 读取 Kotlin 版本。若已是 2.4.0-Beta2 或更高，记录版本并跳过阶段 2.1；否则阶段 2.1 会升级到 2.4.0-Beta2（Maven Central 上首个支持 swiftPMDependencies 的公开版本，无需自定义仓库），并警告用户跨小版本升级可能引入与本迁移无关的破坏性变更，建议先升级验证再迁移。
4. 阶段 1.1：在 `gradle.properties` 中搜索已废弃的 `kotlin.apple.deprecated.allowUsingEmbedAndSignWithCocoaPodsDependencies=true`（KT-64096 的 workaround），记录其存在，阶段 6 必须移除。
5. 阶段 1.2：在所有 `build.gradle.kts` 中搜索禁用 EmbedAndSign 任务的代码（如 `TaskGraph.whenReady` 过滤、`tasks.matching` 块），这是 CocoaPods 时代的 workaround，会连带禁用阶段 5 需要的 `integrateEmbedAndSign`，记录并必须在阶段 6（可能更早）移除。
6. 阶段 1.3：检查第三方 KMP 库是否自带 cinterop klib（如 KMPNotifier 的 `io.github.mirzemehdi:kmpnotifier` 自带 `cocoapods.FirebaseMessaging` 命名空间）。迁移后 swiftPMDependencies 的 cinterop 生成器会跳过这些已有绑定，因此这些 `cocoapods.*` 导入必须原样保留。检测方法：在 Gradle 依赖声明中查找已知库，再与 `import cocoapods.*` 语句交叉比对；若不确定，检查该库是否有 `linkOnly = true` 的 pod 依赖（强指示）。
7. 阶段 1：记录以下内容——CocoaPods 配置、pod 名称与版本、`cocoapods.framework {}` 中的 `baseName`/`isStatic`/部署目标、`linkOnly = true` 的 pod（区分 KMP 包装库与多模块场景：多模块时 `swiftPackage()` 只应声明在直接使用该 pod 的子模块，消费模块不得重复声明）、所有 `import cocoapods.*` 语句（与 1.3 交叉比对区分保留与转换）、pod 到 SPM 的映射、iOS 工程目录（`find . -name "Podfile" -type f`）、是否存在非 KMP 的 CocoaPods 依赖、Podfile 中但不在 `cocoapods {}` 块中的依赖（这些也必须迁移，否则运行时报链接错误）、Xcode 构建阶段中 `embedAndSignAppleFrameworkForXcode` 是否被注释掉、Crashlytics dSYM 上传脚本路径、以及 build 脚本中其他 CocoaPods 相关额外代码（如 `podInstall` 钩子、`Pods.xcodeproj` 补丁、podspec 元数据、`extraSpecAttributes`、`noPodspec()` 等）。
8. 阶段 2：只更新 Kotlin 版本到 `2.4.0-Beta2`（在 `gradle/libs.versions.toml` 中设置 `kotlin = "2.4.0-Beta2"`）。不要升级 Gradle wrapper、KSP 或其他依赖，这些超出本次迁移范围。
9. 阶段 3：先不要移除 `cocoapods {}` 块和 `kotlin("native.cocoapods")` 插件，而是并行添加 `swiftPMDependencies {}`。
10. 阶段 3.1：添加 `group = "org.example.myproject"`（导入命名空间必需）。若项目使用 Compose Multiplatform 资源，`group` 同时是生成资源访问器（`Res.string.*` 等）的命名空间：若已存在则不要改；若首次添加，警告用户现有 Compose 资源调用点会改变命名空间。
11. 阶段 3.2：为每个 pod 添加等价的 SwiftPM 包声明，使用 common-pods-mapping 映射 URL、产品名和 `importedClangModules`。不要升级依赖版本，使用与 `cocoapods {}` 中完全相同的版本（版本变化可能改变 cinterop API 导致无关问题）。版本映射：精确版本 `version = "1.2.3"` 对应 `version = "1.2.3"` 或 `exact("1.2.3")`；乐观版本 `version = "~> 1.2"` 对应 `version = "1.2.0"` 或 `from("1.2.0")`；未指定版本则询问用户要固定到哪个版本。
12. 阶段 3.2：优先使用简单字符串 API `swiftPackage(url = "https://github.com/owner/repo.git", version = "1.0.0", products = listOf("ProductName"))`（自动将 `importedClangModules` 默认为 `products`）；仅在需要精确版本、平台约束或显式 Clang 模块控制时使用带 `url()`/`exact()`/`product()` 包装的类型化 API。注意 `products` 是 SPM 产品名（控制链接），`importedClangModules` 是 cinterop 绑定用的 Clang 模块名（仅当 `discoverClangModulesImplicitly = false` 时需要）；`discoverClangModulesImplicitly` 默认为 `true`，当传递性 C/C++ 模块（Firebase、gRPC）cinterop 失败时设为 `false` 并显式列出所需模块。SPM 产品名与 Clang 模块名不一定一致，务必查映射表。
13. 阶段 3.2：把 Podfile 中但不在 `cocoapods {}` 块中的依赖也加入 `swiftPMDependencies` 的 `products`（若通过 cinterop 使用还需加 `importedClangModules`），否则 App 可能无法构建。不要在同一库套件（如所有 Firebase 产品）中混用 CocoaPods 和 SPM——共享传递依赖会导致重复/冲突符号和运行时 dyld 崩溃；迁移时一次性把该套件所有 pod（包括 Kotlin 不直接使用的纯 Swift pod，作为 `products` 加入，无需 `importedClangModules`）都移到 SPM，添加后重新运行 `integrateLinkagePackage` 重新生成链接包。
14. 阶段 3.3：若 `cocoapods` 块中有 `framework {}` 配置，将其移到各 target 的 `binaries` API：`listOf(iosArm64(), iosSimulatorArm64(), iosX64()).forEach { iosTarget -> iosTarget.binaries.framework { baseName = "Shared"; isStatic = true } }`。推荐 `isStatic = true`（动态框架与 SwiftPM 导入有已知边界情况，会导致链接错误、dyld 崩溃或重复类警告）。若原 `cocoapods.framework {}` 含 `export(project(...))` 或 `transitiveExport = true`，必须保留到新的 `binaries.framework {}` 中（多模块导出子模块必需）。
15. 阶段 3.4：若使用 `dev.gitlive:firebase-*` 等 CocoaPods 时代的 KMP 包装库，需额外两步：A. 切换到 `isStatic = true`（动态框架 + Firebase SPM = 运行时 dyld 崩溃），切换后重新运行 `integrateLinkagePackage`、移除任何 “Embed Frameworks” 拷贝阶段、把链接器标志移到 `OTHER_LDFLAGS`；B. 添加框架搜索路径——在 `build.gradle.kts` 中添加条件 `-F` linkerOpts，并在 Xcode 工程中添加匹配的 `FRAMEWORK_SEARCH_PATHS`。
16. 阶段 3.5：`swiftPackage()` 和 `localSwiftPackage()` 标注了 `@ExperimentalKotlinGradlePluginApi`，在每个调用它们的 `build.gradle.kts` 顶部添加 `@file:OptIn(org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi::class)`；并为 Kotlin 源文件添加 cinterop opt-in：`kotlin.compilerOptions { optIn.add("kotlinx.cinterop.ExperimentalForeignApi") }`。
17. 阶段 4：按公式转换导入：`swiftPMImport.<group>.<module>.<ClassName>`，其中 group 是**声明 swiftPMDependencies 的模块**的 `group` 属性（连字符 `-` 转点 `.`），module 是该模块的 Gradle 模块名（连字符转点，下划线保留），ClassName 是 Objective-C 类名（Firebase 为 `FIR*`，Google Maps 为 `GMS*`）。命名空间使用声明模块的 group+name，而非导入模块的——这是最常见的错误。例如 `import cocoapods.FirebaseAnalytics.FIRAnalytics` 变为 `import swiftPMImport.org.jetbrains.kotlin.firebase.sample.kotlin.library.FIRAnalytics`。
18. 阶段 4：多模块 linkOnly 场景下，消费模块导入 SPM 类时使用**子模块**的 group 和模块名作为命名空间（如 `import swiftPMImport.org.jetbrains.kotlin.google.maps.google.maps.GMSServices`），而非消费模块自己的。Clang 模块名会从导入路径中消失（扁平化），所有类都归到同一个 `swiftPMImport.<group>.<module>` 前缀下。
19. 阶段 4：不要替换解析到第三方 KMP 库自带 cinterop klib 的 `cocoapods.*` 导入（阶段 1.3 识别的），这些必须原样保留——`cocoapods` 前缀是库发布 klib 中的包命名空间，不是真正的 CocoaPods 依赖；swiftPMDependencies 的 cinterop 生成器会跳过依赖 klib 已提供的模块，对这些类使用 `swiftPMImport.*` 会报 “Unresolved reference”。
20. 阶段 4：用正则批量替换所有 Kotlin 源文件（排除阶段 1.3 识别的导入）：`Find: cocoapods\.\w+\.` → `Replace: swiftPMImport.<declaring.module.group>.<declaring.module.name>.`；多模块项目按模块分别用其 group 和 name 运行。批量替换后手动恢复应保留的 `cocoapods.*` 导入。用 `./gradlew :moduleName:compileKotlinIosSimulatorArm64` 查看可用类以确定正确导入路径。
21. 阶段 5.1：构建 CocoaPods workspace 获取迁移命令：`cd /path/to/iosApp` 后运行 `xcodebuild -scheme "$(echo -n *.xcworkspace | python3 -c 'import sys, json; from subprocess import check_output; print(list(set(json.loads(check_output(["xcodebuild", "-workspace", sys.stdin.readline(), "-list", "-json"]))["workspace"]["schemes"]) - set(json.loads(check_output(["xcodebuild", "-project", "Pods/Pods.xcodeproj", "-list", "-json"]))["project"]["schemes"]))[0])')" -workspace *.xcworkspace -destination 'generic/platform=iOS Simulator' ARCHS=arm64 | grep -A5 'What went wrong'`，输出中会包含类似 `XCODEPROJ_PATH='...' GRADLE_PROJECT_PATH=':shared' '.../gradlew' -p '...' ':shared:integrateEmbedAndSign' ':shared:integrateLinkagePackage'` 的命令，运行它。该命令修改 `.xcodeproj` 以在构建时触发 `embedAndSignAppleFrameworkForXcode`；`integrateLinkagePackage` 是一次性设置，无需加为构建阶段。若 `integrateEmbedAndSign` 被跳过，先移除阶段 1.2 的禁用代码再重跑。
22. 阶段 5.1：运行集成后检查 `project.pbxproj` 中的构建阶段脚本，若 `embedAndSignAppleFrameworkForXcode` 被注释（前缀 `#`）则取消注释。`integrateLinkagePackage` 会在 `<iosDir>/` 生成 `KotlinMultiplatformLinkedPackage/` 本地 Swift 包，镜像 `products` 列表以确保 SPM 库链接进最终二进制。
23. 阶段 5.1：在 `.xcodeproj` 中禁用 User Script Sandboxing：`sed -i '' 's/ENABLE_USER_SCRIPT_SANDBOXING = YES/ENABLE_USER_SCRIPT_SANDBOXING = NO/g' "$XCODEPROJ_PATH/project.pbxproj"`（Xcode 16+ 默认开启会阻止 Gradle 构建阶段写入工程目录）；若设置缺失则手动在 app target 的 `buildSettings` 中添加 `ENABLE_USER_SCRIPT_SANDBOXING = NO;`，然后重启 Gradle 守护进程 `./gradlew --stop`。若 xcodebuild 方式失败，参考 troubleshooting 的 “Manual Integration Command Discovery” 回退脚本。
24. 阶段 5.2：若使用 FirebaseCrashlytics 且有 dSYM 上传脚本（阶段 1 步骤 11 识别），把脚本路径从 `${PODS_ROOT}/FirebaseCrashlytics/upload-symbols` 更新为 `"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"`。
25. 阶段 5.3 选项 A（CocoaPods 仅用于 KMP 依赖时完全去集成）：先 `git status --short` 确认路径，不确定时移到备份位置而非直接删除；然后 `cd /path/to/iosApp && pod deintegrate && rm -rf Podfile Podfile.lock Pods/`，用 `XCODEPROJ_NAME=$(basename "$(find . -maxdepth 1 -name "*.xcodeproj" -type d | grep -v Pods | head -1)" .xcodeproj)` 后 `rm -rf "${XCODEPROJ_NAME}.xcworkspace"`，回到项目根目录，用 `ls -1 *.podspec` 列出并删除迁移模块的 podspec（如 `rm -f shared.podspec`）。若 `pod deintegrate` 不可用，参考 troubleshooting 的 “Manual CocoaPods Deintegration from pbxproj”；同时从 `.gitignore` 移除 `Pods/` 并删除 `.xcworkspace`。
26. 阶段 5.3 选项 B（还有其他非 KMP CocoaPods 依赖时部分移除）：只从 `Podfile` 删除 KMP pod 行（如 `pod 'shared', :path => '../shared'`），保留其他非 KMP pod，然后 `cd /path/to/iosApp && pod install`。建议后续把剩余 pod 也迁移到 SPM（多数流行 iOS 库原生支持），在 Xcode 中通过 File → Add Package Dependencies 添加，全部替换后完全去集成 CocoaPods。
27. 阶段 5.4：若自动集成失败，参考 troubleshooting 的 “Manual Xcode Integration Steps” 手动 5 步设置（构建阶段、沙盒、链接包）。
28. 阶段 6.1：从**所有**使用过 CocoaPods 的模块的 `plugins {}` 中移除 `kotlin("native.cocoapods")` 或 `alias(libs.plugins.kotlinCocoapods)`；若所有模块都已迁移，也从 `gradle/libs.versions.toml` 的 `[plugins]` 中移除 `kotlinCocoapods` 条目。
29. 阶段 6.2：从 `build.gradle.kts` 删除整个 `cocoapods { ... }` 块（由阶段 3 添加的 `swiftPMDependencies {}` 和 `binaries.framework {}` 替代），并删除模块目录中生成的 `.podspec` 文件（如 `shared/shared.podspec`）。
30. 阶段 6.3：若阶段 1.1 发现，从 `gradle.properties` 移除 `kotlin.apple.deprecated.allowUsingEmbedAndSignWithCocoaPodsDependencies=true`。
31. 阶段 6.4：清理阶段 1 步骤 12 发现的 CocoaPods 额外代码。podspec 元数据、`noPodspec()`、CocoaPods 任务钩子、`Pods.xcodeproj` 补丁代码可安全移除无需询问用户；非标准 pod 配置（`extraOpts`、`moduleName`）、自定义 cinterop `defFile`、CocoaPods 专用编译/链接标志需要分析，不确定 SPM 是否自动处理时咨询用户。
32. 阶段 7：不要停止直到应用构建成功。此阶段是迭代的——任何步骤失败就诊断错误、修复（参考 troubleshooting 并复查阶段 2–6）、重跑失败步骤，直到构建成功或问题明显超出迁移范围（预先存在的 bug、无关工具问题）。构建成功前不要写迁移报告（阶段 8）。
33. 阶段 7.1：运行 `./gradlew :moduleName:compileKotlinIosSimulatorArm64` 验证 Kotlin 源。若因未解析引用失败，检查导入转换（阶段 4）和 SwiftPM 依赖声明（阶段 3.2）；常见原因：缺少 `importedClangModules`、Clang 模块名错误、应转换的保留 klib 导入（或反之）。
34. 阶段 7.2：运行 `./gradlew :moduleName:linkDebugFrameworkIosSimulatorArm64` 链接框架。若链接失败，检查所有必需 SPM 产品已声明且版本约束正确解析；缺失符号的链接错误通常表示 `swiftPMDependencies` 中遗漏了某个产品，或版本不匹配导致 API 被移除。
35. 阶段 7.3：Gradle 步骤成功后构建 Xcode 工程验证完整应用。若所有 CocoaPods 已移除（选项 A）用 `-project *.xcodeproj`，若还有非 KMP CocoaPods（选项 B）用 `-workspace *.xcworkspace`：`cd /path/to/iosApp` 后用 `xcodebuild -project *.xcodeproj -list -json 2>/dev/null | python3 -c "import sys,json; schemes=json.load(sys.stdin)['project']['schemes']; [print(s) for s in schemes]"` 发现 scheme，再 `xcodebuild -project *.xcodeproj -scheme "<AppScheme>" -destination 'generic/platform=iOS Simulator' ARCHS=arm64 build`（macOS 用 `-destination 'platform=macOS'`）。若 `checkSandboxAndWriteProtection` 失败，说明阶段 5.1 的沙盒未禁用，回去应用修复后重试。若迁移前构建未验证（阶段 1.0 回退），警告用户部分错误可能是与迁移无关的预先存在问题，需与迁移前构建输出对比区分。
36. 阶段 7 构建失败时：不要回滚迁移。读错误日志、复查阶段 2–6、参考 troubleshooting；不确定时向用户呈现选项，不要静默撤销迁移工作。修复后重跑失败的验证步骤，持续迭代直到构建成功。
37. 阶段 8：构建成功后，在项目根目录写 `MIGRATION_REPORT.md`（用 migration-report-template.md 模板），必须包含：1) 迁移前状态（CocoaPods 依赖名称/版本/`linkOnly`、框架配置、`cocoapods.*` 导入、非 KMP pod、非典型配置）；2) 迁移步骤（每阶段的精确变更，非平凡变更附前后代码片段）；3) 导入转换表（每次导入变更，明确标注保留的 `cocoapods.*` 导入及其由哪个自带 klib 提供）；4) 遇到的错误（结构化 `Error #N` 条目：阶段、精确症状、根因、修复、是否可泛化）；5) 非平凡决策（`isStatic` 变更、保留的导入、框架搜索路径、权衡）；6) 变更文件（按类型分组的完整列表：Gradle、Kotlin、Xcode、新建、删除）。

适用边界 · 注意事项

• 项目 Kotlin 版本低于 2.4.0-Beta2 且用户不愿承担跨小版本升级可能引入的破坏性变更时（需先升级验证再迁移）。
• 项目使用 CocoaPods 管理非 KMP 的 iOS 依赖且不打算一并迁移时，只能做部分移除（选项 B），无法完全去集成 CocoaPods。
• 使用第三方 KMP 库自带 cinterop klib（如 KMPNotifier）时，对应的 `cocoapods.*` 导入不能转换，必须原样保留。