Capacitor 8 默认使用 Swift Package Manager (SPM) 创建新 iOS 项目。仍然使用 CocoaPods 的现有应用程序也可以迁移，但安全的迁移路径取决于您的应用程序有多少本机 iOS 自定义。
本指南将指导您了解哪些变化、哪些需要备份，以及两个实用的迁移路径：使用 Capacitor 迁移助手或重新构建 iOS 项目以使用 SPM。
为什么现在迁移
CocoaPods 正在转向只读的主干。当前计划是 CocoaPods 主干将在 2026 年 12 月 2 日停止接受新 podspecs。现有的构建应该继续正常工作，但在切换后新发布和依赖项更新将不会在主干中发布。 SPM 是 __CAPGO_KEEP_0__ 正在采取的方向。__CAPGO_KEEP_1__ 已经支持从 CocoaPods 或 SPM 中选择以来 __CAPGO_KEEP_2__ 6，__CAPGO_KEEP_3__ 8 现在以 SPM 项目作为默认模板创建 iOS 项目。在 __CAPGO_KEEP_0__ SPM 项目中发生了什么变化
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 项目中发生了什么变化
从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/ include:
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swift如果您的应用有一个App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist如果您使用 Firebase- 自定义
.xcconfigcontext - Page/area: Capgo marketing website. Role: Short UI label or navigation item. Message key `custom` (Custom).
也要保留任何原生Swift、Objective-C框架、扩展或SDK文件，除标准Capacitor模板外添加的文件。
选项 1：使用Capacitor迁移助手
当您的 iOS 项目包含自定义原生编辑且不想丢失时，请使用此路径。
从您的Capacitor项目根目录运行助手：
bunx cap spm-migration-assistant助手会移除 CocoaPods 基础设施，创建本地包，生成已安装插件的包引用，并创建生成的 SPM 配置文件。 CapApp-SPM 完成后，请打开项目：
然后按照助手打印的 Xcode 手动步骤进行操作。在大多数项目中，这意味着：
bunx cap open ios添加
- Add
CapApp-SPM添加生成的 - 到应用配置中。
debug.xcconfig添加到应用配置中。 - 解决可能无法转换为SPM的插件的任何警告。
- 从Xcode中构建应用程序一次，然后更新CI。
Xcode项目构建后，同步一次：
bunx cap sync ios选项2：使用SPM重新构建iOS项目
使用此路径时，您的目录接近默认__CAPGO_KEEP_0__模板，您可以安全地在之后恢复自定义文件。 ios/ 目录与默认的Capacitor模板非常接近，您可以安全地在之后恢复自定义文件。
恢复您的应用程序需要的原生文件，然后打开项目：
rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios恢复您的应用程序需要的原生文件，然后打开项目：
bunx cap open ios新Capacitor应用
对于新应用，Capacitor 8使用SPM作为默认包管理器，当添加iOS时：
For a new app, Capacitor 8 uses SPM by default when adding iOS:
bunx cap add ios如果需要明确，可以仍然传递包管理器选项：
bunx cap add ios --packagemanager SPM更新 CI 后续
当应用程序在本地构建后，更新 CI/CD 以便它不再假设 CocoaPods。
移除以下步骤：
pod install也移除以下缓存：
ios/App/Podsios/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/. - 在迁移之后：
CapApp-SPM在Xcode中编译并运行应用程序。 - 在迁移之后：
debug.xcconfig在Xcode中编译并运行应用程序。 - 重新构建
- 在Xcode中
bunx cap sync ios.
或重新构建
- 添加
- 移除遗留的CocoaPods文件。
- 移除
pod install从CI。 - 验证发布签名仍然有效。
- 在至少一个模拟器和一个真实设备上运行应用程序之前发布。
故障排除
如果 Xcode 无法解析包，重置 Xcode 的包缓存并运行 bunx cap sync ios again.
再次。
如果迁移失败是由于插件，检查插件是否有支持SPM的新版本。对于您维护的插件，首先迁移插件包，然后返回到应用程序迁移。 .xcworkspace 当应用程序在本地编译但CI失败时，检查旧的CocoaPods假设。常见原因是强制 pod install 编译路径，一个陈旧的命令，或者缓存 Pods/ 从之前的构建中.
结论
将一个 Capacitor 应用程序迁移到 Swift Package Manager 主要是关于替换 iOS 依赖项的编排. 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企业中 为 __CAPGO_KEEP_0__ 企业产品工作流 ionic 企业插件替代方案 Capgo 替代方案 Capgo 替代方案 为 Capgo 替代方案产品工作流 Capgo 咨询服务 Capgo 高级支持 为产品工作流程在 Capgo 高级支持中。
