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

Swift Package Manager是Capacitor iOS项目的默认方向。如果您的应用程序仍使用CocoaPods，则可以将应用程序本身迁移到SPM而无需重建JavaScriptcode、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 的本地包，并使用它来连接应用程序目标与Capacitor和安装的本机依赖项。

Web构建仍然保持不变。您仍然可以运行Web构建、同步Capacitor、打开Xcode并存档应用程序。主要区别在于CocoaPods不再拥有iOS依赖项图。

您要迁移之前

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

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 文件
签名设置、包标识符、团队ID和分发配置文件
应用程序扩展、原生Swift文件、Objective-C文件或嵌入式框架

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

使用迁移助手

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

npx cap spm-migration-assistant

从您的Capacitor项目根目录运行它。助手会移除CocoaPods集成，创建本地包，生成已安装的原生依赖项的包引用，并添加iOS项目所需的生成配置。 CapApp-SPM 完成后，请打开iOS项目：

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

npx cap open ios

完成Xcode步骤

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

确认

Confirm CapApp-SPM 确认应用程序目标链接了生成的包产品。
如果助手要求，请将生成的__CAPGO_KEEP_0__添加到项目配置中。
在Xcode中解决任何包警告。 debug.xcconfig 确认
确认本地包依赖项__CAPGO_KEEP_0__已添加。
从 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更改。

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

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,更新它到迁移后存在的项目或工作区路径。不要仅因为旧作业使用它们就保留过时的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.
在 Capgo 中，迁移过程中需要注意以下几点：首先，确保您的 iOS 应用程序构建正常；其次，更新本机依赖项以确保它们兼容 SPM；最后，检查您的 Voltbuilder 和 Expo 配置是否正确。 npx cap open ios.
打开项目文件夹并添加 CapApp-SPM 在 Xcode 中如果需要。
添加 debug.xcconfig 在 Xcode 中如果需要。
在 Xcode 中添加 Capacitor 依赖项。
解决包依赖警告。 npx cap sync ios.

在 Xcode 中运行。

迁移后：
从 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 项目之前使用它们，让 agent 审核本机文件、CI 和依赖项兼容性，而不是只运行迁移命令

结论

将 Capacitor 应用迁移到 Swift Package Manager 主要是 iOS 依赖管理的变化。最安全的路径是从干净分支开始， npx cap spm-migration-assistant完成手动 Xcode 步骤，同步一次，最后在应用构建后从 CI 中移除 CocoaPods

如果您的 iOS 项目高度定制化，建议在原地迁移。如果它接近默认 Capacitor 模板，重新创建可能更干净。 ios/ 与 npx cap add ios --packagemanager SPM 可以