要使用 CocoaPods 与 Capacitor 8，请创建 iOS 平台 bunx cap add ios --packagemanager CocoaPods，安装 CocoaPods（Homebrew 或 Gemfile 与 Bundler），并让 bunx cap sync ios 管理 Podfile 并运行 pod install. Capacitor 8仍然完全支持CocoaPods。新项目的默认值已更改为Swift Package Manager。
CocoaPods不再是长期方向，其主干于2026年12月2日变为只读。因此，问题是何时仍然是正确的选择，如何保持其工作，如何清晰地离开它。这份指南涵盖了所有三个方面。
When CocoaPods仍然是正确的选择
保持使用CocoaPods，或者选择CocoaPods，以下情况之一为真:
- A插件需要没有
Package.swift. 在SPM项目中，CLI警告“某些已安装的Capacitor插件与SPM不兼容”，并将该插件排除在外，因此在运行时会出现“插件未实现”的错误。 - A供应商SDK仅以pod形式分发。 某些分析、支付和身份SDK仍然只以CocoaPods形式分发，或者以xcframework形式分发，需要自己包装。
- A Cordova插件依赖于pod。 Capacitor在SPM项目中为Cordova插件生成Swift包，但复杂的插件依赖项往往在CocoaPods中更好地工作。
<podspec>您依赖于podspec子规范 - 您依赖 podspec 子规范 选择 SDK 的变体。 SPM 现在支持包特性， Capacitor 从 CLI 8.3 开始实验性地支持它们（参见 SPM 包特性在 Capacitor )，但插件必须首先定义特性。
- 一个大型、自定义的 Xcode 项目 在本次发布周期中，不值得冒险进行迁移。
包标识符冲突曾经是另一个原因。自 CLI 8.4 以来，您可以在 SPM 中使用 experimental.ios.spm.packageOptions (symlink 或 moduleAliases）在您的 Capacitor 配置中。
如果这些都不适用，请使用 SPM。它不需要 Ruby 工具链、Podfile 和 .xcworkspace.
在 Capacitor 8 中的 CocoaPods 与 SPM
| CocoaPods | Swift 包管理器 | |
|---|---|---|
默认值 cap add ios |
否 | 是 |
| 额外工具 | Ruby + CocoaPods gem | 无，内置于Xcode |
| 项目打开 | ios/App/App.xcworkspace |
ios/App/App.xcodeproj |
| 插件要求 | .podspec |
Package.swift |
| 生成文件 | def capacitor_pods 块内 Podfile |
ios/App/CapApp-SPM/Package.swift |
| 可选功能 | 子规范 | 包依赖特征（Capacitor 中的实验性功能) |
| 未来 | 2026 年 12 月 2 日后只读 | Apple 支持 |
安装 CocoaPods
选择一种方法并在 CI 中使用它。
Homebrew (适合单个开发人员的最简单方法):
brew install cocoapods
pod --versionBundler (为整个团队锁定版本，推荐用于 CI). 在项目根目录或在 Gemfile 当 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 在 ios/App:
source 'https://rubygems.org'
gem 'cocoapods', '~> 1.16'bundle install当CapacitorCLI发现一个 Gemfile 如果提到CocoaPods，它会运行 bundle exec pod install 而不是 pod install. 如果 pod 存储在一个不寻常的地方，请设置 CAPACITOR_COCOAPODS_PATH 到二进制文件。
使用CocoaPods创建一个Capacitor 8应用
bun add @capacitor/ios
bun run build
bunx cap add ios --packagemanager CocoaPods
bunx cap open ioscap open ios 打开 App.xcworkspace. 一定要从工作区中构建。直接打开 App.xcodeproj 会给你 No such module 'Capacitor'.
关于Podfile的解释
这是Capacitor 8生成的Podfile：
require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'
platform :ios, '15.0'
use_frameworks!
install! 'cocoapods', :disable_input_output_paths => true
def capacitor_pods
pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end
target 'App' do
capacitor_pods
# Add your Pods here
end
post_install do |installer|
assertDeploymentTarget(installer)
end你可以和不能够修改的内容：
def capacitor_pods ... end属于 CLI. 每次同步都会将整个块替换为一个指向插件文件夹的单行指令。pod任何您在其中添加的内容都会丢失。node_modules在此添加您的自定义 Pods- ,在此添加您的自定义 Pods
target 'App', aftercapacitor_pods. assertDeploymentTarget__CAPGO_KEEP_0__ 8 必须至少为 15.0。post_install带有额外 pod 和构建设置修复的示例：platform :ios必须至少为 15.0,Capacitor 8。
__CAPGO_KEEP_0__
target 'App' do
capacitor_pods
pod 'GoogleMLKit/BarcodeScanning', '~> 7.0'
end
post_install do |installer|
assertDeploymentTarget(installer)
installer.pods_project.targets.each do |target|
if target.respond_to?(:product_type) && target.product_type == 'com.apple.product-type.bundle'
target.build_configurations.each do |config|
config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
end
end
end
endcode Signing for "X" requires a development team __CAPGO_KEEP_0__
日常命令
# After installing or removing a plugin
bunx cap sync ios
# Use the exact versions in Podfile.lock (good for CI)
bunx cap sync ios --deployment
# Refresh the spec repo when a new pod version isn't found
cd ios/App && pod repo update && pod install
# Update one pod past its locked version
cd ios/App && pod update FirebaseMessagingcap sync ios 也会 xcodebuild clean 在项目中 pod install，所以你不需要手动清理添加插件后
提交 Podfile 和 Podfile.lock， ios/App/Pods/不提交 pod install.
。它会被
从 SPM 切换到 CocoaPods
- 没有反向迁移命令。手动进行：
ios/提交，然后复制到安全的地方 - 删除
ios/. - 运行
bunx cap add ios --packagemanager CocoaPods. - 重新应用本地更改：
Info.plist密钥、特权和能力、签名团队、包标识符、应用图标和启动页资源、URL方案、扩展（小工具、通知服务）、以及任何自定义Swift代码AppDelegate. bunx cap sync ios并构建。
比较旧和新版本之间的差异 ios/App/App 检查旧和新文件夹是找出你错过的最快方法。
解决常见的CocoaPods错误
CocoaPods could not find compatible versions for pod "X". 要么你的本地spec仓库过时，要么两个库需要不兼容的版本。运行 pod install --repo-update 在 ios/App。如果仍然失败，请在错误中读取依赖链，找到带有严格锁定的插件，升级它或 修复其podspec.
The sandbox is not in sync with the Podfile.lock. Run 'pod install'. The Pods folder 不匹配锁文件，通常是在切换 branch 后。运行 bunx cap sync ios.
[!] Unable to find a specification for 'X'. The spec repo 缓存过时或 pod 名字错误。运行 pod repo update.
Unable to find compatibility version string for object version '70' (或 77（或 project.pbxproj （或 objectVersion （或
Sandbox: rsync(...) deny(1) file-write-create. （或 （或（或 （或 (ENABLE_USER_SCRIPT_SANDBOXING（或 No 不适用于 App 目标。
No such module 'Capacitor'. 您打开了 App.xcodeproj. App.xcworkspace打开 bunx cap open ios.
pod: command not found , 或者运行 在 CI 中。 vendor/bundle. 如果没有它，CLI 日志会显示“因为 CocoaPods 未安装，跳过 pod 安装”，并且后续的构建会失败。
更多的 iOS 构建错误在
Capacitor iOS 故障排除指南
- 现有的构建仍然有效。 每个发布的 podspec 都保持可用。
- 不再从 trunk 推送新版本。 从 trunk pull 的 SDK（Firebase、Google ML Kit、供应商 SDK）将不再从那里接收更新。安全修复和新 iOS SDK 支持将仅通过 SPM 或其他渠道发布。
- Capacitor 插件本身不会受到直接影响。 它们从 npm 安装，通过
:path在 Podfile 中引用。它们的传递性 pod依赖项也是如此。
将 CocoaPods 视为一个桥梁。列出哪个依赖项使您继续使用它，并在该依赖项添加 SPM 支持时重新检查。
离开 CocoaPods
当您准备好时：
bunx cap spm-migration-assistant它会 pod deintegrate，移除 Podfile, Podfile.lock 和 App.xcworkspace, 创建 CapApp-SPM, 并写入一个 debug.xcconfig然后添加 CapApp-SPM 作为本地包在 Xcode 中，并设置 debug.xcconfig 作为 Debug 配置文件。完整的教程在 如何将 Capacitor 应用程序迁移到 SPM,以及相关的权衡在 SPM 与 CocoaPods 的 Capacitor.
需要添加 SPM 支持的插件作者应该阅读 将 Capacitor 插件迁移到 SPM.
如果在构建机器上管理 Ruby、CocoaPods 和 Xcode 版本是痛苦的部分, Capgo 构建 在云端使用 Xcode 构建 CocoaPods 和 SPM 项目
