如何迁移一个 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 已经支持从 CocoaPods 或 SPM 中选择以来 Capacitor 6， Capacitor 8 现在以 SPM 项目作为默认模板创建 iOS 项目。

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

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

CapApp-SPM 替换了 Podfile

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

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

debug.xcconfig 替换 Pods 配置

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

迁移后，您可能需要将 debug.xcconfig 添加到 Xcode 项目配置中，如果助手提示您这样做。

每个插件都必须支持 SPM

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

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

什么需要备份

从一个干净的git branch开始，提交当前状态，然后列出你的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，和配置文件设置

也保留任何原生Swift，Objective-C，框架，扩展，或者SDK文件你在标准Capacitor模板外添加的

选项1：使用Capacitor迁移助手

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

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

bunx cap spm-migration-assistant

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

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

bunx cap open ios

添加

作为本地包依赖项。 CapApp-SPM 添加
到应用配置中。 debug.xcconfig 解决任何关于无法转换为SPM的插件的警告。
在更新CI之前，从Xcode中构建应用程序一次。
在Xcode项目构建后，再次同步:

After the Xcode project builds, sync again:

bunx cap sync ios

Option 2: 使用 SPM 重建 iOS 项目

使用此路径时， ios/ 当您的目录接近默认 Capacitor 模板且可以安全地恢复自定义文件时

首先，请确保备份部分列出的文件已提交或复制到安全的地方。然后，使用 SPM 删除并重新创建 iOS 项目：

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

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

bunx cap open ios

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

新 Capacitor 应用

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

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文件和签名设置。
确认应用在迁移之前可以正常构建。

迁移期间：

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

迁移后:

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

故障排除

上下文:支持/高级支持页面或底部支持部分。角色:部分或页面标题。见于:页面support-policy.astro。消息键`support_policy_troubleshooting_title` (支持政策故障排除标题)。 bunx cap sync ios 如果Xcode无法解析包，重置Xcode中的包缓存并运行

再次。

如果迁移失败是由于插件，检查插件是否有支持SPM的新版本。对于您维护的插件，首先迁移插件包，然后返回到应用迁移。 .xcworkspace 当应用在本地编译但CI失败时，检查旧的CocoaPods假设。常见原因是强制 pod install 编译路径， Pods/ 过时的

命令，

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 高级支持。

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