如何将 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会创建一个名为Capacitor的本地包并使用它来连接应用目标和安装的原生依赖项。 CapApp-SPM Capacitor用于连接应用目标和Capacitor以及安装的原生依赖项。

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

在迁移之前

从一个干净的分支开始，并确保当前应用可以编译之前不要改变依赖管理器:

git status
npm run build
npx cap sync ios

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

接下来，检查您的应用在__CAPGO_KEEP_0__中自定义了什么。常见的文件和设置包括: ios/App/，如果存在

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift，如果您使用Firebase
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist自定义
文件 .xcconfig __CAPGO_KEEP_0__
签名设置、包标识符、团队 ID 和分发配置文件
应用扩展、原生 Swift 文件、Objective-C 文件或嵌入式框架

还要检查已安装的 Capacitor 和 Cordova 依赖项。一个 app 级别的 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

__CAPGO_KEEP_0__

如果应用程序使用推送通知、关联域名、后台模式、应用组、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 specs repositories
CI cache keys based on the Podfile

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

npm ci
npm run build
npx cap sync ios

If your CI still builds App.xcworkspace,更新CI配置为项目或工作区路径，迁移后存在的路径。不要因为旧的工作流程使用了它们而保留过时的CocoaPods路径。

Troubleshooting

context: Support / premium support page or footer support section. Role: Section or page heading. Seen in: page support-policy.astro. Message key `support_policy_troubleshooting_title` (Support Policy Troubleshooting Title).

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

先更新依赖项，然后再次运行助手。如果没有SPM兼容的版本，保持应用在CocoaPods上，直到替换该依赖项或维护者添加SPM支持。

Xcode无法解析包 CapApp-SPM 在Xcode中重置包缓存，检查 npx cap sync ios 是否存在作为本地包，重新运行命令。

本地构建成功，但CI失败

查找旧的CocoaPods假设: pod install, Pods/ 缓存 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.

在Xcode中如果需要。

在Xcode中如果需要。
在模拟器或设备上测试原生功能。
从CI中移除CocoaPods命令。
移除CocoaPods仅缓存。
验证归档和发布签名。

使用Capgo技能进行迁移。

如果您使用AI代理来处理迁移，请从__CAPGO_KEEP_0__技能开始。 Capgo Skills 在更改应用结构之前进行审查。

capacitor-best-practices 规划SPM迁移和Xcode后续步骤。 ios/.
cocoapods-to-spm 从构建管道中移除CocoaPods假设。
capacitor-ci-cd 并
debugging-capacitor 查看应用结构之前进行审查 ios-android-logs Migrate __CAPGO_KEEP_0__ 应用到 Swift Package Manager

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

结论

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

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