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

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

本指南将指导您了解更改、备份和两种实用迁移路径：使用 Capacitor 迁移助手或使用 SPM 重构 iOS 项目。

为什么现在迁移

CocoaPods 正在朝着只读的主干发展。当前计划是从年月

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.

What changes in a Capacitor SPM project

SPM 也是 Capacitor 正在朝着的方向。 __CAPGO_KEEP_1__ 已经支持从

年

月 ios/App/Podfile, Podfile.lock, Pods/日开始选择 CocoaPods 或 SPM， __CAPGO_KEEP_3__ 现在创建 iOS SPM 项目作为默认模板。 .xcworkspace.

在 Capacitor SPM 项目中发生了什么变化 CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM CapApp-SPM 替换了 Podfile。

debug.xcconfig 替换 Pods 配置

The migration assistant 也会创建一个生成的 debug.xcconfig. 这个文件包含了 CocoaPods 曾经通过其生成的 xcconfig 文件提供的构建设置.

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

每个插件都必须支持 SPM

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

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

什么需要备份

从一个干净的 Git Branch 开始，提交当前状态，然后列出您的应用依赖的原生文件。

常见需要保留的文件 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 项目有自定义本机编辑时，请使用此路径，不想丢失。

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

助手会移除 CocoaPods 基础设施，创建本地包，生成已安装插件的包引用，并创建生成的 SPM 配置文件。 CapApp-SPM Option 2: Use the __CAPGO_KEEP_0__ migration assistant, if your app has one

当它完成后，打开项目：

bunx cap open ios

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

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

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

bunx cap sync ios

选项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 Branch。
提交当前工作应用。
验证每个安装的插件是否支持 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/ 命令，

或从之前的构建中缓存

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 结论 debug.xcconfig 将应用迁移到 Swift Package Manager 主要是关于替换 iOS 依赖项的编程。 pod install.

它接管依赖项引用， bunx cap spm-migration-assistant. 对于接近默认模板的项目，清洁的 SPM 重构建通常更快，更容易理解。

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