如何将 Capacitor 应用迁移到 Swift Package Manager

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

此指南适用于应用程序团队。它解释了如何将 CocoaPods 迁移到 SPM 的 Capacitor iOS 应用程序、迁移助手所做的更改、在 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 创建一个名为 Capacitor 的本地包，并使用它来连接应用程序目标和 Capacitor 以及安装的本机依赖项。 CapApp-SPM Web 构建仍然保持不变。您仍然可以运行 Web 构建、同步 Capacitor、打开 Xcode 并存档应用程序。主要区别在于 CocoaPods 不再拥有 iOS 依赖项图表。

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

从一个干净的 branch 开始，并确保当前应用程序可以构建之前不要改变依赖管理器:

然后提交工作状态。迁移会影响生成的 iOS 项目文件，因此有一个干净的回滚点很重要。

git status
npm run build
npx cap sync ios

Editor

Migrate your Capacitor app to SPM 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 自定义
文件
签名设置、包标识符、团队 ID 和分发配置文件

Also check your installed Capacitor and Cordova dependencies. An app-level SPM migration can be blocked by a native dependency that has no SPM-compatible path. Update those packages before migrating when possible.

另外，请检查已安装的 __CAPGO_KEEP_0__ 和 Cordova 依赖项。一个应用级 SPM 迁移可能会被阻止一个没有 SPM 兼容路径的原生依赖项。尽可能更新这些包之前迁移。

For most existing apps, start with the official Capacitor migration assistant:

npx cap spm-migration-assistant

对于大多数现有的应用程序，请从以下位置开始使用官方 Capacitor 迁移助手： CapApp-SPM 生成包引用，用于安装的本机依赖项，并添加所需的iOS项目配置。

完成后，请打开iOS项目：

npx cap open ios

在关闭终端之前，请阅读助手输出。如果它要求您完成手动Xcode步骤，请在同步之前完成。

完成Xcode步骤

在Xcode中，检查应用程序项目和目标配置：

确认 CapApp-SPM Capacitor被添加为本地包依赖项。
确认应用程序目标链接了生成的包产品。
将生成的 debug.xcconfig 添加到项目配置中，如果助手要求，请在此处添加。
在Xcode中解决任何包警告。
从Xcode中构建应用程序一次。

如果 Xcode 无法解析包，使用 文件 > 包 > 重置包缓存, 然后再次解析包。

重新同步并编译

在 Xcode 配置完成后，返回终端并同步 Capacitor:

npx cap sync ios

然后从 Xcode 再次编译。直到从 Xcode 中进行干净的编译成功为止，不要认为迁移完成，因为发布签名、权限、应用扩展和包解析在 Xcode 中进行验证。

如果应用使用推送通知、关联域名、后台模式、应用组、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 更改。

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

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 specs 仓库
基于 Podfile 的 CI 缓存键

迁移后的基本 CI 流程应该安装 JavaScript 依赖项，构建 Web 应用，同步 Capacitor，并使用 Xcode 构建

npm ci
npm run build
npx cap sync ios

如果您的 CI 还在构建 App.xcworkspace,更新 CI 到迁移后的项目或工作区路径，不要因为旧的任务使用了它们而保留过时的 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.
在Xcode中打开 npx cap open ios.
添加 CapApp-SPM 如果需要
在 Xcode 中添加 debug.xcconfig 如果需要，请在 Xcode 中添加
解决包警告
在 npx cap sync ios.

迁移后：

从 Xcode 中构建应用
在模拟器或设备上测试本机功能
从 CI 中移除 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 可以更干净。