Capacitor 8 默认使用 Swift Package Manager (SPM) 创建新的 iOS 项目。仍在使用 CocoaPods 的现有应用也可以迁移，但最安全的路径取决于你的应用有多少原生 iOS 定制。
本指南将介绍变更内容、需要备份的项目，以及两种实用的迁移路径：使用 Capacitor 迁移助手，或使用 SPM 重新搭建 iOS 项目。
为什么现在迁移
CocoaPods 正在转向只读 trunk。目前的计划是 CocoaPods trunk 将在以下日期停止接受新的 podspec： 2026年12月2日. 现有的 build 应能继续正常工作，但切换后，依赖 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 会创建一个本地 package，名为 CapApp-SPM. 该 package 将成为 Capacitor 引用原生 iOS plugin 依赖的核心位置。Capacitor CLI 会更新 CapApp-SPM 因此，同步 plugin 时请将其视为生成产物，避免手动编辑。
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 布局更复杂的插件可能需要手动处理。
先备份哪些内容
在改动 iOS 项目之前，先从一个干净的 git 分支开始，并提交当前状态。然后列出你的 App 依赖的原生文件。
需要从 ios/App/ 中保留的常见文件包括：
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swift（如果您的应用有的话）App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist（如果您使用 Firebase）- 自定义
.xcconfig文件 - 签名设置、Bundle Identifier、Team ID 以及 Provisioning Profile 设置
同时请保留您在标准 Capacitor 模板之外添加的任何原生 Swift、Objective-C、framework、extension 或 SDK 文件。
方案 1：使用 Capacitor 迁移助手
如果您的 iOS 项目包含不希望丢失的自定义原生改动，请选择此路径。
在 Capacitor 项目根目录下运行该助手：
bunx cap spm-migration-assistant该助手会移除 CocoaPods 基础设施，创建本地 CapApp-SPM package，根据已安装的插件生成 package references，并生成 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 模板。代价是你必须仔细重新配置签名、entitlements、Firebase 文件、原生源码改动以及任何自定义 Xcode 设置。
新的 Capacitor 应用
对于新应用，Capacitor 8 添加 iOS 时默认使用 SPM：
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 build 和 Capacitor sync 步骤。一个典型的 iOS job 会安装 JavaScript 依赖、构建 web 资源、sync Capacitor，然后用 Xcode 构建：
bun install --frozen-lockfile
bun run build
bunx cap sync ios迁移检查清单
迁移前：
- 创建一个新的 git 分支。
- 提交当前可正常运行的 App。
- 确认所有已安装的 plugin 都支持 SPM。
- 记录自定义的 iOS 文件和签名设置。
- 确认迁移前 App 能正常 build。
迁移过程中：
- 运行
bunx cap spm-migration-assistant或重新生成脚手架ios/. - 添加
CapApp-SPM如有需要，请在 Xcode 中操作。 - 添加
debug.xcconfig如有需要，请在 Xcode 中操作。 - 恢复应用专属的原生文件。
- 运行
bunx cap sync ios.
迁移后：
- 在 Xcode 中构建并运行应用。
- 移除残留的 CocoaPods 文件。
- 移除
pod install从 CI 中移除。 - 验证 Release 签名是否仍可正常工作。
- 发布前，请务必在至少一个模拟器和一台真机上运行应用。
故障排除
如果 Xcode 无法解析包，请在 Xcode 中重置 Package Cache 并运行 bunx cap sync ios 再次尝试。
如果迁移因某个插件而失败，请检查该插件是否有支持 SPM 的更新版本。对于你维护的插件，先迁移插件包，再回来迁移 App。
当 App 在本地构建成功但 CI 失败时，请检查是否存在旧的 CocoaPods 假设。常见原因包括强制指定的 .xcworkspace 构建路径、过时的 pod install 命令，或 Pods/ 之前构建留下的缓存。
总结
将 Capacitor App 迁移到 Swift Package Manager，主要就是替换 iOS 的依赖配置。 CapApp-SPM 接管依赖引用， debug.xcconfig 替换生成的 CocoaPods 构建配置，且 CI 不再需要 pod install.
对于自定义的 iOS 项目，建议从 bunx cap spm-migration-assistant这里开始。对于接近默认模板的项目，用 SPM 干净地重新搭建项目通常更快，也更容易理解。
资源
继续阅读《如何将 Capacitor App 迁移到 Swift Package Manager》
如果你正在使用 如何将 Capacitor App 迁移至 Swift Package Manager 要规划迁移和企业运营，请将其与 Capgo 企业版 用于 Capgo Enterprise 中的产品工作流， Ionic Enterprise 插件替代方案 用于 Ionic Enterprise 插件替代方案的产品工作流， Capgo 替代方案 用于 Capgo 替代方案的产品工作流， Capgo 咨询 适用于 Capgo Consulting 的产品工作流，以及 Capgo 高级支持 适用于 Capgo Premium Support 的产品工作流。
