Swift Package Manager是Capacitor iOS项目的默认方向。如果您的应用仍使用CocoaPods，则可以将应用本身迁移到SPM而无需重建JavaScriptcode、Android项目或发布流程
本指南适用于应用团队。它解释了如何将Capacitor iOS应用从CocoaPods迁移到SPM、迁移助手所做的更改、在Xcode中需要检查的内容以及如何清理CI后应用构建
应用中的更改
基于CocoaPods的Capacitor应用依赖于文件，如
ios/App/Podfileios/App/Podfile.lockios/App/Pods/ios/App/App.xcworkspace
基于SPM的Capacitor应用将iOS依赖项的编排移到Swift Package Manager。在迁移期间，Capacitor会创建一个名为 CapApp-SPM 并使用它连接应用目标与Capacitor以及安装的本机依赖项。
Web构建仍然保持不变。您仍然运行一个Web构建，同步Capacitor，打开Xcode，并存档应用。主要区别在于CocoaPods不再拥有iOS依赖图表。
在迁移之前
从一个干净的分支开始，并确保当前应用构建正常之前不要更改依赖管理器:
git status
npm run build
npx cap sync ios然后提交工作状态。迁移会触及生成的iOS项目文件，因此有一个干净的回滚点很重要。
接下来，查看您的应用在下面自定义了什么 ios/App/常见文件和设置需要保留包括:
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swift，如果存在App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist，如果您使用Firebase- 自定义
.xcconfig文件 - 签名设置，包标识符，团队ID和分发配置文件
- app 扩展、native Swift 文件、Objective-C 文件或嵌入式框架
另外检查已安装的 Capacitor 和 Cordova 依赖项。一个 app 级别的 SPM 迁移可能会被一个没有 SPM 兼容路径的 native 依赖项阻塞。尽可能更新这些包之前迁移。
使用迁移助手
对于大多数现有的 app，首先使用官方 Capacitor 迁移助手：
npx cap spm-migration-assistant从 Capacitor 项目根目录运行它。助手会移除 CocoaPods 集成，创建本地包，生成已安装 native 依赖项的包引用，并添加 iOS 项目所需的生成配置。 CapApp-SPM 完成后打开 iOS 项目：
在关闭终端之前阅读助手输出。如果它要求您完成手动 Xcode 步骤，请在再次同步之前完成。
npx cap open ios完成 Xcode 步骤
在 Xcode 中检查 app 项目和目标配置：
确认
- 是作为本地包依赖项添加的。
CapApp-SPM是 - 确认应用目标链接生成的包产品。
- 将生成的
debug.xcconfig添加到项目配置中，如果助手要求的话。 - 在Xcode中解决任何包警告。
- 从Xcode中构建应用一次。
如果Xcode无法解决包，使用 文件>包>重置包缓存,然后再次解决包。
在Xcode配置完成后，返回终端并同步__CAPGO_KEEP_0__：
在 Xcode 配置完成后，返回终端并同步 Capacitor
npx cap sync ios如果应用使用推送通知、关联域名、后台模式、应用组、Firebase或任何本机__CAPGO_KEEP_0__配置，请在构建成功后在模拟器或设备上运行这些流程。
If the app uses push notifications, associated domains, background modes, app groups, Firebase, or any native SDK configuration, run those flows on a simulator or device after the build succeeds.
Alternative: 使用 SPM 重建 iOS
如果您的 ios/ 文件夹与默认Capacitor模板相似，可以通过使用SPM重新创建它来更快地完成，而不是在原地迁移。
folder 是接近默认 __CAPGO_KEEP_0__ 模板，
rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios可以更快地使用 SPM 重建它，而不是在原地迁移。
对于新建的Capacitor应用，Capacitor 8 默认会为 iOS 项目创建 SPM。
npx cap add ios然后恢复您的应用特定的本机文件和设置。这个路径给您一个干净的 SPM 项目，但如果您没有先清单它们，很容易丢失自定义 Xcode 更改。
npx cap add ios --packagemanager SPM对于新 __CAPGO_KEEP_0__ 应用，__CAPGO_KEEP_1__ 8 默认使用 SPM 创建 iOS 项目：
您仍然可以明确地使用 SPM：
清理 CocoaPods 副产品
pod installSPM 应用构建后，
ios/App/Podsios/App/Podfile.lock- 从本地脚本和 CI 中删除 CocoaPods 假设。
- 基于 Podfile 的 CI 缓存键
迁移后，CI 流程应该安装 JavaScript 依赖项，构建 Web 应用，同步 Capacitor，并使用 Xcode 构建:
npm ci
npm run build
npx cap sync ios如果您的 CI 还在构建 App.xcworkspace,请将其更新为迁移后的项目或工作区路径。不要因为旧作业使用它们而保留过时的 CocoaPods 路径。
故障排除
助手警告不兼容的依赖项
首先更新依赖项，然后再次运行助手。如果不存在 SPM 兼容的版本，请将应用保留在 CocoaPods 上，直到您替换该依赖项或维护者添加 SPM 支持。
Xcode 无法解析包
在 Xcode 中重置包缓存，检查 CapApp-SPM 是否存在作为本地包的 npx cap sync ios ，然后再次运行
本地应用构建成功，但 CI 失败
寻找旧的 CocoaPods 假设: pod install, Pods/ 缓存 Podfile.lock 缓存键或指向已删除的 .xcworkspace.
签名或权限已更改
与迁移后的 Xcode 目标进行比较。恢复包标识符、团队、配置文件、权限文件、功能和扩展设置。
迁移清单
迁移之前:
- 创建一个分支。
- 确认当前 iOS 应用程序可以编译。
- 提交当前工作状态。
- 清点自定义本机文件和签名设置。
- 更新已有新版 SPM 兼容版本的本机依赖项。
在迁移过程中：
- 运行
npx cap spm-migration-assistant. - Run
npx cap open ios. - 在 Xcode 中
CapApp-SPMOpen the project with - 在 Xcode 中
debug.xcconfigOpen the project with - 在 Xcode 中添加
- 运行
npx cap sync ios.
Add
- in Xcode if required.
- 在 Xcode 中解决包依赖警告。
- 移除 CocoaPods 命令。
- 移除 CocoaPods 仅限缓存。
- 验证存档和发布签名。
使用 Capgo 技能进行迁移
如果您使用 AI agent 处理迁移，开始从 Capgo 技能 而不是空白提示。对于此工作最有用的技能是：
capacitor-best-practices在更改之前检查应用结构ios/.cocoapods-to-spm规划 SPM 迁移和 Xcode 后续步骤capacitor-ci-cd移除 CocoaPods 假设从构建管道debugging-capacitor和ios-android-logs调查设备仅限问题
使用它们在更改 iOS 项目之前，以便代理审计本机文件、CI 和依赖兼容性而不是只运行迁移命令。
结论
将 Capacitor 应用程序迁移到 Swift Package Manager 主要是 iOS 依赖管理的变化。最安全的路径是从干净的 branch 开始，运行 npx cap spm-migration-assistant完成手动 Xcode 步骤，同步一次，仅在应用程序构建后从 CI 中删除 CocoaPods。
如果您的 iOS 项目高度定制化，则在原地迁移。如果它接近默认 Capacitor 模板，则重建 ios/ 可以更干净。 npx cap add ios --packagemanager SPM 资源
