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

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

在迁移之前

从一个干净的 branch 开始，并确保当前应用构建成功之前不要改变依赖管理器：

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 项目：

After it finishes, open the iOS project:

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：重新创建 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 默认创建 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 路径。

故障排除

在此区域：支持/高级支持页面或底部支持部分。角色：部分或页面标题。见于：页面 support-policy.astro。消息键 `support_policy_troubleshooting_title` (支持政策故障排除标题)。

助手警告不兼容的依赖项

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.
在Xcode中添加 CapApp-SPM 在Xcode中添加
在Xcode中添加 debug.xcconfig 在Xcode中添加
解决包依赖警告。
运行 npx cap sync ios.

迁移后:

从Xcode中构建应用程序。
在模拟器或设备上测试原生功能。
从CI中移除CocoaPods命令。
移除CocoaPods仅缓存。
验证归档和发布签名。

使用Capgo技能进行迁移

如果您使用AI代理来处理迁移，请从 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 可以更干净

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