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

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

This guide walks through what changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with SPM。

Why migrate now

CocoaPods 正在朝着只读的树干发展。当前计划是 CocoaPods 树干将在 2026 年 12 月 2 日停止接受新的 podspecs。 . 现有的构建应该继续正常工作，但新发布和依赖更新将不会在切换后在树干上发布。SPM 也是 __CAPGO_KEEP_0__ 正在朝着的方向。 __CAPGO_KEEP_1__ 已经支持从 __CAPGO_KEEP_2__ 6 开始选择 CocoaPods 或 SPM， __CAPGO_KEEP_3__ 8 现在以 SPM 项目作为默认模板创建 iOS 项目。

SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.

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

Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.

在 CocoaPods 应用中，iOS 依赖项通过

, 和生成的 ios/App/Podfile, Podfile.lock, Pods/__CAPGO_KEEP_0__ 8 使用 Swift Package Manager (SPM) 默认创建新 iOS 项目。仍然使用 CocoaPods 的现有应用也可以迁移，但安全的迁移路径取决于您的应用有多少本地 iOS 自定义。 .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, but plugins with more complex Objective-C and Swift layouts may need manual work.

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

删除运行：

步骤

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 重构通常更快、更容易理解

资源

从 How to Migrate a Capacitor App to Swift Package Manager 继续

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

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