Cómo usar CocoaPods con Capacitor 8 (y cuándo no hacerlo)

To use CocoaPods with Capacitor 8, create the iOS platform with bunx cap add ios --packagemanager CocoaPods, instale CocoaPods (Homebrew o un archivo Gemfile con Bundler), y permita bunx cap sync ios gestionar el archivo Podfile y ejecute pod install.Capacitor 8 sigue apoyando CocoaPods. Solo se cambió el valor por defecto para nuevos proyectos a Swift Package Manager.

CocoaPods ya no es la dirección a largo plazo, y su tronco se convierte en solo lectura el 2 de diciembre de 2026. Así que la verdadera pregunta es cuándo sigue siendo la elección correcta, cómo mantenerlo funcionando y cómo dejarlo limpio. Este guía cubre todos tres.

Cuándo CocoaPods sigue siendo la elección correcta

Quédese en, o elija, CocoaPods cuando sea cierto alguno de estos:

• A un plugin que necesitas no Package.swift. En un proyecto de SPM, el CLI advierte: “Algunos plugins Capacitor instalados no son compatibles con SPM” y lo deja fuera, por lo que falla en tiempo de ejecución con “plugin no implementado”.
• Un proveedor SDK se distribuye solo como un pod. Algunas SDK de análisis, pago e identidad aún envían CocoaPods solo, o envían un xcframework que tendrías que envolver tú mismo.
• Un plugin de Cordova depende de pods. Capacitor genera un paquete Swift para plugins de Cordova en proyectos de SPM, pero los complejos con <podspec> dependencias funcionan mejor con CocoaPods.
• Dependes de subspecs de podspec para elegir SDK variantes. SPM tiene características de paquete ahora, y Capacitor las soporta experimentalmente desde CLI 8.3 (ver Características de paquete SPM en Capacitor), pero el plugin debe definir las características primero.
• Un gran proyecto de Xcode personalizado donde una migración no vale la pena el riesgo en este ciclo de lanzamiento.

Las colisiones de identidad de paquetes solían ser otra razón. Desde CLI 8.4, puedes trabajar alrededor de ellas en SPM con experimental.ios.spm.packageOptions (symlink o moduleAliasesen su Capacitor configuración.

Si ninguna de estas se aplica, utilice SPM. No necesita ninguna herramienta de Ruby, ningún archivo Podfile y ningún .xcworkspace.

CocoaPods vs SPM en Capacitor 8

Instale CocoaPods

Elige un enfoque y úsalo en todas partes, incluyendo CI.

Homebrew (más simple para un desarrollador):

brew install cocoapods
pod --version

Bundler (pincha la versión para toda la equipo, recomendado para CI). Crea un Gemfile en la raíz del proyecto o en ios/App:

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

bundle install

Cuando el Capacitor CLI encuentra un Gemfile que menciona CocoaPods, ejecuta bundle exec pod install en lugar de pod installSi pod vive en algún lugar inusual, establece CAPACITOR_COCOAPODS_PATH hasta la versión binaria.

Crea una aplicación Capacitor 8 con CocoaPods

bun add @capacitor/ios
bun run build
bunx cap add ios --packagemanager CocoaPods
bunx cap open ios

cap open ios abre App.xcworkspaceSiempre construye desde el workspace. Al abrir App.xcodeproj directamente te da No such module 'Capacitor'.

El archivo Podfile, explicado

Esto es el archivo Podfile que Capacitor 8 genera:

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

Lo que puedes y no puedes tocar:

• def capacitor_pods ... end pertenece a CLI. En cada sincronización reemplaza el bloque completo con uno pod Cualquier cosa que agregues dentro se pierde. node_modulesNada que agregues dentro de esto se conserva.
• Agregue sus propios pods bajo target 'App', después capacitor_pods.
• assertDeploymentTarget eleva cualquier pod con un objetivo de despliegue por debajo de 15.0 hasta 15.0, lo que evita advertencias de Xcode sobre objetivos no compatibles. Manténgalo y agregue su propio post_install logic dentro del mismo bloque.
• platform :ios debe ser al menos 15.0 para Capacitor 8.

Example with an extra pod and a build setting fix:

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

El bucle deshabilita la firma de code para los objetivos de paquetes de recursos. Signing for "X" requires a development team en los pods que envían paquetes de recursos. Sólo agregue esto si encuentra ese error.

Comandos diarios

# 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 también ejecuta xcodebuild clean en el proyecto después pod install, por lo que no necesita una limpieza manual después de agregar plugins.

Commit Podfile y Podfile.lockNo cometas ios/App/Pods/Se regenera automáticamente por pod install.

Cambiar una aplicación existente de SPM a CocoaPods

No existe un comando de migración inversa. Hazlo a mano:

1. Cometer, luego copiar ios/ en algún lugar seguro.
2. Eliminar ios/.
3. Ejecutar bunx cap add ios --packagemanager CocoaPods.
4. Reaplicar cambios nativos: Info.plist clave, permisos y capacidades, equipo de firmado, identificador de paquete, iconos de la aplicación y activos de pantalla de bienvenida, esquemas de URL, extensiones (widgets, servicio de notificaciones), y cualquier código Swift personalizado AppDelegate.
5. bunx cap sync ios y construye.

Diferir entre el antiguo y el nuevo ios/App/App es la forma más rápida de detectar lo que te has perdido.

Corrigiendo errores comunes de CocoaPods

CocoaPods could not find compatible versions for pod "X". O bien, tu repositorio de especies locales está desfasado o dos pods requieren versiones incompatibles. Ejecuta pod install --repo-update en ios/App. Si sigue fallando, lee la cadena de dependencias en el error, encuentra el plugin con la pin estricta, actualízalo o actualice su podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. El Pods carpeta no coincide con el archivo de bloqueo, generalmente después de cambiar de rama. Ejecuta bunx cap sync ios.

[!] Unable to find a specification for 'X'. The spec repo cache is stale or the pod name is wrong. Run pod repo update.

Unable to find compatibility version string for object version '70' (o 77. Su proyecto de Xcode utiliza un formato más nuevo que el gem CocoaPods/xcodeproj entiende. Actualice CocoaPods a la última versión. Si no puede, haga una copia de seguridad project.pbxproj y establezca objectVersion a un valor que CocoaPods admite.

Sandbox: rsync(...) deny(1) file-write-create. Xcode's sandbox de usuario bloquea el script de CocoaPods de incorporación. Configuración de compilaciónestablezca Sandbox de scripts de usuario (ENABLE_USER_SCRIPT_SANDBOXING) a No para el objetivo de la aplicación.

No such module 'Capacitor'. Abrió App.xcodeproj . Abra App.xcworkspaceo ejecutar bunx cap open ios.

pod: command not found en CI. Instale CocoaPods en el trabajo, o utilice Bundler con una caché vendor/bundleSin él, los registros CLI dicen "Saltando la instalación de pods porque CocoaPods no está instalado" y el compilado falla más tarde.

Se cubren más errores de compilación de iOS en el Guía de depuración de iOS de Capacitor.

La fecha de lectura de CocoaPods en el tronco

Los mantenedores de CocoaPods anunciaron que el tronco, el repositorio de especificaciones central, se convierte en solo de lectura el 2 de diciembre de 2026, después de una prueba en noviembre de 2026. ¿Qué eso significa para una aplicación Capacitor:

• Los compilados existentes siguen funcionando. Todos los podspecs publicados siguen disponibles.
• No hay nuevas versiones a través del tronco. Los SDKs que se extraen del tronco (Firebase, Google ML Kit, SDKs de proveedores) dejan de recibir actualizaciones allí. Las correcciones de seguridad y el nuevo soporte de iOS SDK solo se enviarán a través de SPM o otros canales.
• Capacitor plugins themselves are not affected directly. Se instalan desde npm y se refieren a :path en el archivo Podfile. Sus dependencias de pods transitorias son.

Trata a CocoaPods como un puente. Indica qué dependencia te mantiene en él, y revisa cuando esa dependencia agregue soporte a SPM.

Moverse fuera de CocoaPods

Cuando estés listo:

bunx cap spm-migration-assistant

Ejecuta pod deintegrate, elimina el Podfile, Podfile.lock y App.xcworkspacecrea CapApp-SPM, y escribe un debug.xcconfigy luego agregas CapApp-SPM como un paquete local en Xcode y establecer debug.xcconfig como el archivo de configuración de depuración. El recorrido completo está en cómo migrar su Capacitor aplicación a SPM, y las compensaciones se cubren en SPM vs CocoaPods para Capacitor.

Los autores de plugins que necesitan agregar soporte de SPM deben leer migrar un Capacitor plugin a SPM.

Si el manejo de versiones de Ruby, CocoaPods y Xcode en las máquinas de compilación es lo doloroso. Capgo Construcción construye proyectos CocoaPods y SPM en la nube con la versión actual de Xcode.