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

Capacitor 8 使用 Swift Package Manager (SPM) 默认创建新 iOS 项目。仍然使用 CocoaPods 的现有应用也可以迁移，但安全的路径取决于您的应用有多少本地 iOS 自定义。

本指南将指导您了解哪些变化、哪些需要备份，以及迁移的两个实用路径：使用 Capacitor 迁移助手或重新构建 iOS 项目使用 SPM。

为什么现在迁移

CocoaPods 正在朝着只读的树干发展。当前计划是 CocoaPods 树干将在 2026 年 12 月 2 日停止接受新 podspecs。现有的构建应该继续正常工作，但新发布和依赖项更新，依赖于树干的发布将不会在此之后发布在此之后。

SPM 是 Capacitor 正在朝着的方向。 Capacitor 支持从 Capacitor 6 开始选择 CocoaPods 或 SPM， Capacitor 8 现在以 SPM 项目作为默认模板创建 iOS 项目。

在 Capacitor SPM 项目中发生了什么变化

从 CocoaPods 到 SPM 迁移替换了 iOS 依赖层。Web 应用、Android 项目和大多数 Capacitor 工作流命令保持不变。

CapApp-SPM 替换了 Podfile

在 CocoaPods 应用中，iOS 依赖项通过 ios/App/Podfile, Podfile.lock, Pods/、和生成的 .xcworkspace.

在 SPM 应用中，Capacitor 创建一个名为 CapApp-SPM的本地包。这个包成为 Capacitor 引用本地 iOS 插件依赖的中心位置。Capacitor CLI 会在您同步插件时更新，因此请将其视为生成的输出，并避免手动编辑它。 CapApp-SPM debug.xcconfig 替换 Pods 配置

迁移助手还创建一个生成的

文件。这个文件包含 CocoaPods 通过其生成的 xcconfig 文件提供的构建设置。 debug.xcconfig迁移后，您可能需要将

添加到 Xcode 项目配置中，如果助手提示您这样做。 debug.xcconfig 每个插件都必须支持 SPM

您不能在同一个 __CAPGO_KEEP_0 iOS 项目中混合使用 CocoaPods 和 SPM。迁移之前，请检查每个 CAPGO_KEEP_1__ 和 Cordova 插件，

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

进行转换，但具有更复杂的 Objective-C 和 Swift 布局的插件可能需要手动工作。 capacitor-plugin-converter__CAPGO_KEEP_0__ is a placeholder for 'Pods',

What to first backup

从一个干净的git branch开始，提交当前状态，然后再接触iOS项目。然后列出你的app依赖的原生文件。

常见的需要保留的文件 ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, 如果你的app有一个
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, 如果你使用Firebase
自定义 .xcconfig 文件
签名设置，bundle标识符，团队ID，和配置文件设置

Also preserve any native Swift, Objective-C, framework, extension, or SDK files you added outside the standard Capacitor template.

选项1：使用 Capacitor 迁移助手

使用这个路径时，你的iOS项目有自定义的原生编辑，你不想丢失。

从您的Capacitor项目根目录运行助手:

bunx cap spm-migration-assistant

助手会移除 CocoaPods 基础设施、创建本地包、生成已安装插件的包引用以及创建生成的 SPM 配置文件。 CapApp-SPM 当它完成后，请打开项目：

然后按照助手打印的 Xcode 手动步骤进行操作。在大多数项目中，这意味着：

bunx cap open ios

将其添加为本地包依赖项。

将生成的 CapApp-SPM 添加到应用配置中。
解决因无法转换为 SPM 的插件而出现的任何警告。 debug.xcconfig 在更新 CI 之前，从 Xcode 中构建应用程序一次。
在 Xcode 项目构建后，同步一次：
Build the app from Xcode once before updating CI.

After the Xcode project builds, sync again:

bunx cap sync ios

Option 2: 使用 SPM 重建 iOS 项目

当你的目录接近默认 __CAPGO_KEEP_0__ 模板时，使用这个路径，安全地恢复自定义文件后 ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

恢复你的应用需要的原生文件，然后打开项目：

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

这种方法通常比在原地迁移更干净，因为它为你提供了一个新的 __CAPGO_KEEP_0__ 8 iOS 模板。然而，这意味着你必须小心地重新应用签名、权限、Firebase 文件、原生源代码修改以及任何自定义 Xcode 设置

bunx cap open ios

新 Capacitor 应用

对于新应用，Capacitor 8 默认使用 SPM 添加 iOS：

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

迁移后更新 CI

bunx cap add ios --packagemanager SPM

当应用在本地编译后，更新 CI/CD 以便它不再假设 CocoaPods

移除运行:步骤

移除 CocoaPods 步骤

pod install

也移除缓存:

ios/App/Pods
ios/App/Podfile.lock
如果您的工作流程仅为此应用程序缓存了CocoaPods specs仓库，请移除它们

保持您的常规Web构建和Capacitor同步步骤。一个典型的iOS任务应该安装JavaScript依赖项、构建Web资产、同步Capacitor，然后使用Xcode构建：

bun install --frozen-lockfile
bun run build
bunx cap sync ios

迁移清单

迁移之前：

创建一个新的git分支
提交当前工作应用
验证每个安装的插件是否支持SPM
记录自定义iOS文件和签名设置
在迁移之前确认应用程序构建

在迁移期间：

运行 bunx cap spm-migration-assistant 或重新构建 ios/.
添加 CapApp-SPM 如果需要，请在 Xcode 中添加。
添加 debug.xcconfig 如果需要，请在 Xcode 中添加。
恢复应用特有的本机文件。
运行 bunx cap sync ios.

迁移后：

在 Xcode 中构建并运行应用。
删除 CocoaPods 文件。
删除 pod install 从 CI 中删除。
验证发布签名仍然有效。
在发布前，务必在至少一个模拟器和一个真实设备上运行应用。

故障排除

如果 Xcode 无法解析包，重置 Xcode 中的包缓存并重新运行。 bunx cap sync ios 如果迁移失败是由于插件原因，检查是否有插件具有 SPM 支持的新版本。对于您维护的插件，首先迁移插件包，然后返回到应用迁移。

当应用在本地编译成功但 CI 失败时，检查 CocoaPods 的旧假设。常见原因包括强制的

编译路径、过时的 .xcworkspace 命令或缓存 pod install 来自之前的构建。 Pods/ 结论

将 __CAPGO_KEEP_0__ 应用迁移到 Swift Package Manager 主要是关于替换 iOS 依赖性编程。

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 处理依赖引用 debug.xcconfig 替换生成的 CocoaPods 构建配置，CI 不再需要 pod install.

针对定制的 iOS 项目， bunx cap spm-migration-assistant对于接近默认模板的项目，清洁的 SPM 重构通常更快，更容易理解

资源

继续阅读如何将 Capacitor 应用程序迁移到 Swift Package Manager

如果您正在使用 如何将 Capacitor 应用程序迁移到 Swift Package Manager 为企业迁移和运营做好准备，连接它 Capgo 企业在 Capgo 企业中， Ionic 企业插件替代品在 Ionic 企业插件替代品中， Capgo 替代品在 Capgo 替代品中， Capgo 咨询在 Capgo 咨询中，以及 Capgo 高级支持在 Capgo 高级支持中。