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

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

本指南将介绍更改、备份和两个实用迁移路径：使用 Capacitor 迁移助手或使用 SPM 重构 iOS 项目。

为什么现在迁移

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.

Capacitor SPM 项目中的更改

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

CapApp-SPM 替换了 Podfile

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

SPM 应用中,Capacitor创建一个名为 CapApp-SPM的本地包。这成为Capacitor引用本地 iOS 插件依赖项的中心位置。CapacitorCLI更新 CapApp-SPM 当您同步插件时，__CAPGO_KEEP_1____CAPGO_KEEP_2__会更新，因此请将其视为生成的输出，并避免手动编辑。

debug.xcconfig 替换 Pods 配置

迁移助手还创建了一个生成的 debug.xcconfig文件。这文件携带了 CocoaPods 通过其生成的 xcconfig 文件提供的构建设置。

迁移后，您可能需要在 Xcode 项目配置中添加 debug.xcconfig 如果助手告诉您这样做的话。

每个插件都必须支持SPM

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

如果一个插件尚未支持SPM，请更新它、替换它或首先迁移插件。简单的Swift插件通常可以使用Ionic的 capacitor-plugin-converter,但具有更复杂的Objective-C和Swift布局的插件可能需要手动工作。

什么需要备份

从一个干净的git branch开始，提交当前状态，然后在触摸iOS项目之前列出您的应用依赖的本机文件。

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

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 和分发配置文件设置

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 添加生成的
__CAPGO_KEEP_1__ debug.xcconfig 配置应用程序。
解决任何关于无法转换为 SPM 的插件的警告。
在更新 CI 之前，使用 Xcode 构建应用程序一次。

在 Xcode 项目构建后，再次同步：

bunx cap sync ios

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

Capacitor

bunx cap add ios

如果需要明确，请仍然传递包管理器选项：

bunx cap add ios --packagemanager SPM

迁移后更新CI

一旦应用在本地编译完成，更新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文件和签名设置。
确认应用程序在迁移之前构建。

迁移期间：

Run bunx cap spm-migration-assistant 或重新生成 ios/.
Add CapApp-SPM 在Xcode中添加，如果需要。
Add debug.xcconfig 在Xcode中添加，如果需要。
恢复应用程序特有的本机文件。
Run bunx cap sync ios.

迁移后：

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

故障排除

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

当应用程序在本地构建但 CI 失败时，检查旧的 CocoaPods 假设。常见原因包括强制

构建路径，陈旧的 .xcworkspace 缓存 pod install command, or caching Pods/ from previous builds.

Conclusion

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM takes over the dependency references, debug.xcconfig replaces generated CocoaPods build configuration, and CI no longer needs pod install.

For customized iOS projects, start with bunx cap spm-migration-assistant. For projects close to the default template, a clean SPM re-scaffold is often faster and easier to reason about.

Resources

Capacitor应用迁移到Swift Package Manager的继续指南

如果您正在使用 Capacitor应用迁移到Swift Package Manager的继续指南 以计划迁移和企业运营为目的,连接它与 Capgo企业在Capgo企业中,产品工作流程在Ionic Enterprise Plugin Alternatives中,产品工作流程在__CAPGO_KEEP_0__ Alternatives中,产品工作流程在Capgo Alternatives中,产品工作流程 Capgo咨询服务 Capgo咨询服务为Capgo咨询服务的产品工作流程，和 Capgo高级支持为Capgo高级支持的产品工作流程。

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