如何将您的 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 和安装的本机依赖项。 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

接下来，审查应用在下面自定义的内容：。常见的文件和设置包括：

__CAPGO_KEEP_0__ ios/App/__CAPGO_KEEP_1__

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 集成、创建本地 CapApp-SPM 包、为安装的本机依赖项生成包引用，并添加 iOS 项目所需的生成配置。

完成后，请打开 iOS 项目：

npx cap open ios

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

完成 Xcode 步骤

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

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

如果 Xcode 无法解决包，使用 文件 > 包裹 > 重置包缓存然后重新解决包依赖。

重新同步和构建。

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

npx cap sync ios

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

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

Alternative: 使用 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 默认创建 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 兼容的版本存在，请在替换该依赖项或维护者添加 SPM 支持之前继续使用 CocoaPods。

Xcode 无法解析包

在 Xcode 中重置包缓存，检查是否 CapApp-SPM 存在本地包，并运行 npx cap sync ios 再试一次。

本地应用可以编译，但 CI 失败

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

签名或权限已更改

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

迁移清单

迁移之前：

创建一个分支。
确认当前iOS应用程序的构建。
提交当前工作状态。
查看自定义原生文件和签名设置。
更新已经有更新的SPM兼容版本的原生依赖项。

在迁移期间：

运行 npx cap spm-migration-assistant.
打开项目使用 npx cap open ios.
添加 CapApp-SPM 在Xcode中如果需要。
添加 debug.xcconfig 在Xcode中如果需要。
解决包警告。
Run npx cap sync ios.

迁移后：

从 Xcode 构建应用。
在模拟器或设备上测试本机功能。
从 CI 中移除 CocoaPods 命令。
从 CocoaPods-only 缓存中移除。
验证存档和发布签名。

使用 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依赖管理的变化。最安全的路径是从干净的分支开始，运行 npx cap spm-migration-assistant完成手动Xcode步骤，同步一次，最后在应用构建成功后从CI中移除CocoaPods

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

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