Is CocoaPods still supported in Capacitor 8?

Yes. Capacitor 8 supports both CocoaPods and Swift Package Manager. Only the default for new iOS platforms changed to SPM. Existing CocoaPods apps keep working, and you can create a new one with bunx cap add ios --packagemanager CocoaPods.

What happens to my app when CocoaPods trunk becomes read-only?

The CocoaPods team plans to make trunk read-only on December 2, 2026. Existing pod versions stay installable, so builds keep working. No new versions are published through trunk afterwards, so dependencies such as SDKs pulled from trunk stop receiving updates there. Capacitor plugins installed from npm use local paths and are not affected directly.

Can one Capacitor app use SPM for some plugins and CocoaPods for others?

Not through the Capacitor CLI. The CLI manages plugins with one package manager per iOS project. In an SPM project, plugins without a Package.swift are skipped with a warning. If you depend on a CocoaPods-only plugin, the whole iOS project needs CocoaPods until that plugin adds SPM support.

How do I switch an existing Capacitor app from SPM back to CocoaPods?

There is no automatic command. Back up the ios folder, delete it, run bunx cap add ios --packagemanager CocoaPods, then reapply your native changes such as Info.plist keys, entitlements, signing, app icons and extensions.

Should I run pod install myself?

Usually not. bunx cap sync ios rewrites the Capacitor section of the Podfile and runs pod install for you, using bundle exec when a Gemfile is present. Run pod commands yourself only for repo updates or targeted pod update calls.

如何在 Capacitor 8 中使用 CocoaPods（以及何时不要用）

若要在 Capacitor 8 中使用 CocoaPods，请用以下命令创建 iOS 平台： bunx cap add ios --packagemanager CocoaPods，安装 CocoaPods（用 Homebrew，或用 Bundler 配合 Gemfile），然后让 bunx cap sync ios 管理 Podfile 并运行 pod install. Capacitor 8 仍然完全支持 CocoaPods。仅新项目的默认设置改为了 Swift Package Manager。

CocoaPods 不再是长期方向，其 trunk 将于 2026 年 12 月 2 日变为只读。所以真正的问题是：何时它仍是正确选择、如何保持其正常运行，以及如何干净地迁移走。本指南涵盖这三点。

何时仍应选择 CocoaPods

只要满足以下任一条件，就继续使用或选择 CocoaPods：

你需要的插件没有 Package.swift. 在 SPM 项目中，CLI 会发出“部分已安装的 Capacitor 插件与 SPM 不兼容”的警告并排除该插件，导致运行时出现“plugin is not implemented”错误。
某个厂商的 SDK 仅以 pod 形式分发。 部分分析、支付和身份验证 SDK 仍仅支持 CocoaPods，或者仅提供需要自行封装的 xcframework。
某个 Cordova 插件依赖 pods。 Capacitor 会为 SPM 项目中的 Cordova 插件生成 Swift package，但带有复杂 <podspec> 依赖项的插件在 CocoaPods 下通常运行得更好。
你依赖 podspec 子规范 来选择 SDK 变体。SPM 现在支持包特性，Capacitor 从 CLI 8.3 开始实验性支持它们（参见 Capacitor 中的 SPM 包特性），但插件必须先定义特性。
大型且高度定制的 Xcode 项目 在本发布周期内迁移风险过高。

包标识符冲突曾是另一个原因。从 CLI 8.4 开始，你可以在 SPM 中通过 experimental.ios.spm.packageOptions (symlink 或 moduleAliases）在 Capacitor 配置中解决它们。

如果以上情况均不适用，请使用 SPM。它无需 Ruby 工具链、Podfile 或 .xcworkspace.

Capacitor 8 中的 CocoaPods 与 SPM 对比

	CocoaPods	Swift Package Manager
新项目默认 `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 中为实验性）
未来	Trunk 自 2026 年 12 月 2 日起只读	Apple 官方支持

安装 CocoaPods

选择一种方案并统一使用，包括 CI。

Homebrew （最适合个人开发者）：

brew install cocoapods
pod --version

Bundler （为整个团队锁定版本，推荐用于 CI）。创建一个 Gemfile 在项目根目录或 ios/App:

source 'https://rubygems.org'
gem 'cocoapods', '~> 1.16'

bundle install

当 Capacitor CLI 发现 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 ios

cap open ios 打开 App.xcworkspace。始终从 workspace 构建。打开 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： target 'App'，放在……之后 capacitor_pods.
assertDeploymentTarget 会把任何 deployment target 低于 15.0 的 pod 提升到 15.0，避免 Xcode 报不受支持目标的警告。保留它，并添加你自己的 post_install 逻辑，放在同一个代码块内。
platform :ios 对于 Capacitor 8，必须至少为 15.0。

带额外 pod 和构建设置修复的示例：

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
end

该循环会禁用 resource bundle targets 的 code 签名。它修复了 Signing for "X" requires a development team 适用于包含资源 bundle 的 pods。仅在遇到该错误时添加。

日常命令

# 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 FirebaseMessaging

cap 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 密钥、权限与能力、签名团队、bundle identifier、App 图标与启动图资源、URL schemes、扩展（小组件、通知服务）以及任何自定义 Swift 代码，存放在 AppDelegate.
bunx cap sync ios 并进行构建。

对比新旧 ios/App/App 文件夹是发现遗漏内容最快的方法。

修复常见的 CocoaPods 错误

CocoaPods could not find compatible versions for pod "X". 要么是本地 spec 仓库已过期，要么是两个 pod 要求的版本不兼容。请运行 pod install --repo-update 中的 ios/App。如果仍然失败，请查看错误中的依赖链，找到设置了严格版本限制的 plugin，将其升级或修改其 podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. 本指南中介绍的 Pods 文件夹与 lock file 不匹配，通常发生在切换分支后。请运行 bunx cap sync ios.

[!] Unable to find a specification for 'X'. spec repo 缓存已过期或 pod 名称错误。请运行 pod repo update.

Unable to find compatibility version string for object version '70' (或 77）。您的 Xcode 项目使用的格式比您的 CocoaPods/xcodeproj gem 支持的更新。请将 CocoaPods 更新到最新版本。如果无法更新，请备份 project.pbxproj 并设置 objectVersion 为您的 CocoaPods 支持的版本。

Sandbox: rsync(...) deny(1) file-write-create. Xcode 的用户脚本沙盒阻止了 CocoaPods 嵌入脚本。在 Build Settings 中调高部署目标，设置 用户脚本沙盒 (ENABLE_USER_SCRIPT_SANDBOXING) 到否用于 App 目标。

No such module 'Capacitor'. 你已打开 App.xcodeproj。打开 App.xcworkspace，或运行 bunx cap open ios.

pod: command not found CI 中设置。 在作业中安装 CocoaPods，或使用带有缓存的 Bundler vendor/bundle。如果没有它，CLI 会记录“跳过 pod install，因为未安装 CocoaPods”，并且构建稍后会失败。

更多 iOS 构建错误请参阅 Capacitor iOS 故障排除指南.

CocoaPods trunk 只读日期

CocoaPods 维护者宣布，中央 spec 仓库 trunk 将在 2026 年 11 月初的试运行之后，于 2026 年 12 月 2 日转为只读。这对 Capacitor 应用意味着什么：

现有构建仍可正常工作。 所有已发布的 podspec 保持可用。
无法再通过 trunk 发布新版本。 你从 trunk 拉取的 SDK（Firebase、Google ML Kit、厂商 SDK）将不再在那里获得更新。安全修复和新的 iOS SDK 支持只会通过 SPM 或其他渠道发布。
Capacitor 插件本身不受直接影响。 它们从 npm 安装，并在 Podfile 中通过 :path 引用。但它们间接依赖的 pod 则会受影响。

把 CocoaPods 当作过渡桥梁。列出哪些依赖让你还离不开它，等这些依赖支持 SPM 后再重新评估。

从 CocoaPods 迁移

准备好后：

bunx cap spm-migration-assistant

运行 pod deintegrate，移除 Podfile, Podfile.lock 以及 App.xcworkspace，创建 CapApp-SPM，并写入 debug.xcconfig。然后添加 CapApp-SPM 作为 Xcode 中的本地 package，并设置 debug.xcconfig 作为 Debug 配置文件。完整步骤见如何将你的 Capacitor 应用迁移到 SPM，权衡取舍见 Capacitor 的 SPM 与 CocoaPods 对比.

需要添加 SPM 支持的插件作者请阅读将 Capacitor 插件迁移到 SPM.

如果管理构建机器上的 Ruby、CocoaPods 和 Xcode 版本是最头疼的部分， Capgo 构建 Capgo 会在云端使用最新 Xcode 构建 CocoaPods 和 SPM 项目。