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

Capacitor 8将新iOS项目以Swift Package Manager（SPM）为默认。现有的应用仍使用CocoaPods的应用也可以迁移，但安全的路径取决于您的应用有多少本地iOS定制。

本指南将指导您了解变化、备份什么以及两个实用的迁移路径：使用Capacitor迁移助手或重新构建iOS项目以SPM。

为什么现在迁移

CocoaPods正在向只读的树转变。当前计划是CocoaPods树将在 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配置

The migration assistant also creates a generated debug.xcconfig本文件包含了 CocoaPods 通过其生成的 xcconfig 文件提供的构建设置。

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

每个插件都必须支持SPM

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

如果一个插件还不支持SPM，更新它，替换它，或者先将插件迁移到Swift。简单的Swift插件经常可以通过Ionic的 capacitor-plugin-converter但是，需要手动工作的插件可能是那些包含复杂Objective-C和Swift布局的。

首先备份什么

从一个干净的git branch开始，提交当前状态，然后再接触iOS项目。接着列出你的app依赖的原生文件。

常见文件保留 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 完成后，请打开项目：

__CAPGO_KEEP_0__

bunx cap open ios

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

添加 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仓库，则移除CocoaPods specs仓库

保持您的常规Web构建和 Capacitor 同步步骤。一个典型的iOS工作应该安装JavaScript依赖项、构建Web资产、同步 Capacitor，然后使用Xcode构建：

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

迁移清单

迁移之前:

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

迁移期间:

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

迁移后：

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

故障排除

区域/页面：支持/高级支持页面或底部支持部分。角色：部分或页面标题。见：页面 support-policy.astro。消息键 `support_policy_troubleshooting_title` (支持政策故障排除标题)。 bunx cap sync ios 再次.

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

当应用程序在本地构建但CI失败时，请检查旧的CocoaPods假设。常见原因是强制的构建路径、过时的命令或缓存来自之前的构建。 .xcworkspace 结论 pod install 将__CAPGO_KEEP_0__应用程序迁移到Swift Package Manager主要是关于替换iOS依赖项的编排。 Pods/ 取代了依赖项引用、替换了生成的CocoaPods构建配置，CI不再需要

对于定制的iOS项目，请从

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 取代了依赖项引用、替换了生成的CocoaPods构建配置，CI不再需要 debug.xcconfig 对于定制的iOS项目，请从 pod install.

开始。对于接近默认模板的项目，清洁的SPM重新布局通常更快更容易理解。 bunx cap spm-migration-assistant取代了依赖项引用、替换了生成的CocoaPods构建配置，CI不再需要

资源

继续阅读如何将 Capacitor 应用程序迁移到 Swift Package Manager

如果您正在使用 如何将 Capacitor 应用程序迁移到 Swift Package Manager 规划迁移和企业运营，连接它与 Capgo 企业 for the product workflow in Capgo Enterprise, 用于 __CAPGO_KEEP_0__ 企业产品工作流程中的产品工作流程中，为Ionic Enterprise插件替代品的产品工作流程 Capgo替代品为Capgo替代品的产品工作流程 Capgo咨询为Capgo咨询，并且 Capgo高级支持为Capgo高级支持的产品工作流程

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