Capacitor 8以Swift Package Manager（SPM）为默认创建新的iOS项目。仍使用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配置
Capgo的迁移助手还会创建一个生成的 debug.xcconfig本文件包含了 CocoaPods 通过其生成的 xcconfig 文件提供的构建设置。
在迁移后，您可能需要添加 debug.xcconfig 如果助手提示您这样做，请将其添加到 Xcode 项目配置中。
每个插件都必须支持SPM
您不能在同一个 Capacitor iOS 项目中混合使用 CocoaPods 和 SPM。 在迁移之前，请检查每个 Capacitor 和 Cordova 插件 package.json.
如果一个插件还不支持SPM，更新它，替换它，或者先将插件迁移到SPM。简单的Swift插件通常可以使用Ionic的 capacitor-plugin-converter但是，需要手动处理的Objective-C和Swift布局更复杂的插件可能会更多。
首先备份什么
从一个干净的git branch开始，提交当前状态，然后列出你的app依赖的原生文件。
常见文件保留 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 基础设施、创建本地包、从已安装的插件生成包引用并创建生成的 SPM 配置文件。 CapApp-SPM 完成后，请打开项目：
选项 2：使用 __CAPGO_KEEP_0__ CLI 迁移工具
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/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 文件和签名设置。
- 确认应用在迁移之前可以正常编译。
迁移期间:
- 在 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/ SPM会取代依赖项引用、替换生成的CocoaPods构建配置，CI不再需要
对于定制化的iOS项目，请从
Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 迁移iOS依赖项 debug.xcconfig SPM取代依赖项引用 pod install.
替换生成的CocoaPods构建配置 bunx cap spm-migration-assistantCI不再需要
资源
继续从如何将 Capacitor 应用程序迁移到 Swift Package Manager
如果您正在使用 如何将 Capacitor 应用程序迁移到 Swift Package Manager 规划迁移和企业运营，连接它与 Capgo 企业 为 Capgo 企业产品工作流 Ionic 企业插件替代方案 为Ionic Enterprise插件替代品的产品工作流程 Capgo替代品 为Capgo替代品的产品工作流程 Capgo咨询 为Capgo咨询的产品工作流程,并 Capgo高级支持 为Capgo高级支持的产品工作流程。
