How to Migrate a Capacitor App to Swift Package Manager

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

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

为什么现在迁移

CocoaPods 正在向只读的树转变。当前计划是 CocoaPods 树将于 2026 年 12 月 2 日停止接受新 podspecs 2026 年 12 月 2 日 . 现有构建应该继续正常工作，但在切换后，依赖于 trunk 的新发布和依赖项更新将不会在那里发布。

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

什么在 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 配置

迁移助手也创建了一个生成的 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 开始，提交当前状态，然后再修改 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、框架、扩展或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的插件的任何警告。
从Xcode构建应用程序一次之前更新CI:

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

bunx cap sync ios

选项2：使用SPM重新构建iOS项目

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

首先，请确保备份部分列出的文件已提交或复制到安全的地方。然后，移除并重新创建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仓库，如果你的工作流程仅为此应用缓存它们

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with Xcode:

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

迁移清单

迁移之前:

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

在迁移期间：

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

在迁移后：

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

Troubleshooting

如果Xcode无法解析包，重置Xcode包缓存并重新运行。 bunx cap sync ios again.

如果迁移失败是由于插件，请检查插件是否有支持SPM的新版本。对于您维护的插件，首先迁移插件包，然后返回到应用迁移。

当应用在本地编译成功，但CI失败时，检查旧的CocoaPods假设。常见原因是强制的 .xcworkspace 构建路径、过时的 pod install 命令或缓存 Pods/ 来自之前的构建。

结论

将Capacitor应用迁移到Swift Package Manager主要是关于替换iOS依赖项的编排。 CapApp-SPM SPM debug.xcconfig 取代了依赖项引用、替换了生成的CocoaPods构建配置，CI不再需要 pod install.

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

资源

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

如果您正在使用 如何将 Capacitor App 迁移到 Swift Package Manager 为迁移和企业运营规划，连接它到 Capgo 企业为企业产品工作流程中的Capgo 用于 __CAPGO_KEEP_0__ 企业产品工作流 Ionic 企业插件替代品 Capgo 替代方案为 Capgo Alternatives 流程 Capgo 咨询为 Capgo 咨询流程 Capgo Premium 支持为 Capgo Premium 支持流程

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