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

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

本指南适用于应用团队。它解释了如何将CapacitoriOS应用从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 依赖项。一个 app-level SPM 迁移可能会被一个没有 SPM 兼容路径的原生依赖项阻塞。尽可能更新那些包之前迁移。

使用迁移助手

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

npx cap spm-migration-assistant

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

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

npx cap open ios

完成 Xcode 步骤

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

确认

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

如果 Xcode 无法解决包，使用 然后再次解决包。再次同步和构建

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

After Xcode is configured, return to the terminal and sync Capacitor:

npx cap sync ios

File > Packages > Reset Package Caches

如果应用程序使用推送通知、关联域名、后台模式、应用组、Firebase 或任何本机SDK配置，建置成功后，请在模拟器或设备上运行这些流程。

iOS 可以使用 SPM 重建

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

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

npm ci
npm run build
npx cap sync ios

如果您的CI仍然构建 App.xcworkspace,请更新它以使用迁移后的项目或工作区路径。不要仅因为旧作业使用它们就保留过时的CocoaPods路径。

故障排除

助手警告关于不兼容的依赖项

首先更新依赖项并重新运行助手。如果不存在SPM兼容版本，请在您替换该依赖项或维护者添加SPM支持之前保持应用在CocoaPods上。

Xcode无法解析包

在Xcode中重置包缓存、检查 CapApp-SPM 是否作为本地包存在，并重新运行 npx cap sync ios 助手

The app locally builds but CI fails

查找旧的 CocoaPods 假设: pod install, Pods/ caches, Podfile.lock 缓存键或指向已删除的 .xcworkspace.

签名或权限已更改

与迁移前的项目进行的迁移 Xcode 目标进行比较。恢复包标识符、团队、分发配置文件、权限文件、功能和扩展设置。

迁移清单

迁移之前:

创建一个分支。
确认当前 iOS 应用程序可以编译。
提交当前工作状态。
清点自定义本机文件和签名设置。
更新已经有更新SPM兼容版本的本地依赖项。

在迁移期间：

运行 npx cap spm-migration-assistant.
打开项目文件夹 npx cap open ios.
在Xcode中添加 CapApp-SPM 如果需要在Xcode中添加
解决包的警告。 debug.xcconfig 运行
迁移后：
从Xcode中构建应用程序。 npx cap sync ios.

__CAPGO_KEEP_0__

在Xcode中添加
在模拟器或设备上测试本地功能。
从CI中移除CocoaPods命令。
从CocoaPods中移除缓存。
验证归档和发布签名。

使用Capgo技能进行迁移

如果您使用AI代理来处理迁移，从Capgo技能而不是空白提示。对于此工作最有用的技能是：

capacitor-best-practices 在更改之前review应用结构 ios/.
cocoapods-to-spm 规划SPM迁移和Xcode后续步骤
capacitor-ci-cd 从构建管道中移除CocoaPods假设
debugging-capacitor 和 ios-android-logs To investigate device-only issues after migration.

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

结论

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

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