如何将你的 Capacitor App 迁移到 Swift Package Manager

Swift Package Manager 是 Capacitor iOS 项目的默认方向。如果您的应用仍在使用 CocoaPods，您可以将应用本身迁移到 SPM，而无需从头重建您的 JavaScript code、Android 项目或发布工作流。

本指南面向应用团队。它解释了如何将 Capacitor iOS 应用从 CocoaPods 迁移到 SPM，迁移助手会更改哪些内容，在 Xcode 中您还需要检查什么，以及应用构建后如何清理 CI。

应用中的变更

基于 CocoaPods 的 Capacitor 应用依赖于以下文件：

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

基于 SPM 的 Capacitor 应用会把 iOS 依赖配置迁移到 Swift Package Manager。迁移过程中，Capacitor 会创建一个名为 CapApp-SPM 的本地 package，并用它把应用 target 与 Capacitor 以及已安装的原生依赖连接起来。

Web build 仍然照常工作。你仍然要运行 web build、sync Capacitor、打开 Xcode 并 archive 应用。主要区别在于 CocoaPods 不再掌管 iOS 依赖图。

迁移之前

先从一个干净的分支开始，并确保在更换依赖管理器之前当前应用能正常 build：

git status
npm run build
npx cap sync ios

然后提交当前的工作状态。迁移会改动生成的 iOS 项目文件，所以保留一个干净的回滚点很重要。

接下来，检查你的应用在以下路径下自定义了哪些内容 ios/App/。需要保留的常见文件和设置包括：

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift（如果存在）
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist（如果您使用 Firebase）
自定义 .xcconfig 文件
签名设置、Bundle Identifier、Team ID 和 Provisioning Profiles
App Extensions、原生 Swift 文件、Objective-C 文件或内嵌 Framework

同时检查已安装的 Capacitor 和 Cordova 依赖。如果某个原生依赖没有兼容 SPM 的路径，可能会阻塞应用级 SPM 迁移。条件允许时，请在迁移前更新这些包。

使用迁移助手

对于大多数现有应用，请先使用官方的 Capacitor 迁移助手：

npx cap spm-migration-assistant

在 Capacitor 项目根目录下运行它。该助手会移除 CocoaPods 集成，创建本地 CapApp-SPM package，为已安装的原生依赖生成 package references，并添加 iOS 项目所需的生成配置。

完成后，打开 iOS 项目：

npx cap open ios

关闭终端前，请先阅读助手输出。如果提示需要完成手动 Xcode 步骤，请在再次同步前完成这些操作。

完成 Xcode 步骤

在 Xcode 中，检查 App 项目和 Target 配置：

确认 CapApp-SPM 已作为本地包依赖添加。
确认 App Target 已链接生成的包产品。
将生成的 debug.xcconfig 添加到项目配置中（如果助手要求）。
解决 Xcode 中的任何包警告。
从 Xcode 构建一次 App。

如果 Xcode 无法解析包，请使用 File > Packages > Reset Package Caches，然后重新解析包。

同步并再次构建

配置好 Xcode 后，返回终端并同步 Capacitor：

npx cap sync ios

然后再次从 Xcode 构建。在 Xcode 中成功完成 clean build 之前，不要认为迁移已完成，因为 release signing、entitlements、app extensions 和包解析都在那里进行验证。

如果应用用到推送通知、Associated Domains、后台模式、App Groups、Firebase 或任何原生 SDK 配置，请在构建成功后到模拟器或真机上跑一遍这些流程。

备选方案：用 SPM 重建 iOS

如果你的 ios/ 如果文件夹和默认 Capacitor 模板很接近，用 SPM 重新创建可能比原地迁移更快。

仅在提交或备份了所有需要的原生文件和签名设置后，才使用此路径：

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

然后恢复应用专属的原生文件和设置。这条路径能给你一个干净的 SPM 项目，但如果没有先清点，很容易丢失自定义的 Xcode 改动。

对于新的 Capacitor 应用，Capacitor 8 默认使用 SPM 创建 iOS 项目：

npx cap add ios

你仍然可以显式指定：

npx cap add ios --packagemanager SPM

清理 CocoaPods 残留文件

在 SPM 应用构建完成后，请从本地脚本和 CI 中移除残留的 CocoaPods 假设。

移除如下步骤：

pod install

同时移除只为 CocoaPods 存在的缓存：

ios/App/Pods
ios/App/Podfile.lock
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 目标与迁移前的项目进行比较。恢复 bundle identifier、团队、provisioning profile、entitlements 文件、capabilities 和扩展设置。

迁移检查清单

迁移前：

创建分支。
确认当前 iOS 应用可以正常构建。
提交当前工作状态。
清点自定义原生文件和签名设置。
更新已有更新 SPM 兼容版本的本地依赖。

迁移过程中：

运行 npx cap spm-migration-assistant.
使用以下工具打开项目： npx cap open ios.
添加 CapApp-SPM 如有需要，请在 Xcode 中操作。
添加 debug.xcconfig 如有需要，请在 Xcode 中操作。
解决包警告。
运行 npx cap sync ios.

迁移后：

从 Xcode 构建应用。
在模拟器或真机上测试原生功能。
从 CI 中移除 CocoaPods 命令。
移除仅用于 CocoaPods 的缓存。
验证归档和发布签名。

使用 Capgo Skills 进行迁移

如果你使用 AI 代理来处理迁移，请从以下开始： Capgo 技能而不是一个空白 prompt。这项工作最有用的技能包括：

capacitor-best-practices 在改动前审查 App 结构 ios/.
cocoapods-to-spm 规划 SPM 迁移和 Xcode 后续步骤。
capacitor-ci-cd 从 build pipeline 中移除关于 CocoaPods 的假设。
debugging-capacitor 以及 ios-android-logs 排查迁移后仅在真机上出现的问题。

在修改 iOS 项目前使用它们，让 agent 审查原生文件、CI 和依赖兼容性，而不是只运行迁移命令。

总结

将 Capacitor App 迁移到 Swift Package Manager 主要是一项 iOS 依赖管理变更。最稳妥的做法是从干净分支开始，运行 npx cap spm-migration-assistant，完成手动 Xcode 步骤，再次同步，并且只在 App 构建成功后才从 CI 中移除 CocoaPods。

如果你的 iOS 项目经过深度定制，请原地迁移。如果它接近默认的 Capacitor 模板，则重新创建 ios/ 配合 npx cap add ios --packagemanager SPM 可以更简洁。