Capacitor 8会以Swift Package Manager（SPM）为默认创建新的iOS项目。仍然使用CocoaPods的现有应用也可以迁移，但安全的路径取决于您的应用有多少本地iOS定制。
本指南将指导您了解变化、备份什么以及迁移的两个实用路径：使用Capacitor迁移助手或重新构建iOS项目以使用SPM。
为什么现在迁移
CocoaPods正在向只读的树转变。当前的计划是CocoaPods树停止接受新的podspecs December 2, 2026现有构建应该继续正常工作，但在切换后，依赖于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.
In an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM 的本地包。这成为__CAPGO_KEEP_0__引用本地iOS插件依赖项的中心位置。__CAPGO_KEEP_1__ __CAPGO_KEEP_2__更新
当您同步插件时会更新，因此请将其视为生成的输出，并避免手动编辑它。
迁移助手还会创建一个生成的 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/App/ include:
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swift, 如果您的应用程序只有一个App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/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 基础设施，创建本地 CapApp-SPM 包，生成已安装插件的包引用，并创建生成的 SPM 配置文件。
当它完成时，请打开项目：
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/Podsios/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 SPM接管依赖项引用、 debug.xcconfig 替换生成的CocoaPods构建配置，CI不再需要 pod install.
对于定制的iOS项目，请从 bunx cap spm-migration-assistant开始。对于接近默认模板的项目，清洁的SPM重新构建通常更快更容易理解。
资源
从如何将 Capacitor 应用程序迁移到 Swift Package Manager 中继续
如果您正在使用 如何将 Capacitor 应用程序迁移到 Swift Package Manager 为了计划迁移和企业运营，连接它与 Capgo Enterprise 在 Capgo Enterprise 中的产品工作流程 Ionic Enterprise 插件替代方案 Ionic 企业插件替代方案的产品工作流程 Capgo替代方案 for the product workflow in Capgo Alternatives, Capgo咨询 for the product workflow in Capgo Consulting, and Capgo高级支持 for the product workflow in Capgo Premium Support.
