Come usare CocoaPods con Capacitor 8 (e quando evitarlo)

Per usare CocoaPods con Capacitor 8, crea la piattaforma iOS con bunx cap add ios --packagemanager CocoaPods, installa CocoaPods (tramite Homebrew o un Gemfile con Bundler) e lascia che bunx cap sync ios gestisca il Podfile ed esegua pod install. Capacitor 8 supporta ancora pienamente CocoaPods. È cambiato solo il valore predefinito per i nuovi progetti, ora Swift Package Manager.

CocoaPods non è più la direzione a lungo termine e il suo trunk diventerà read-only il 2 dicembre 2026. La vera domanda è quindi quando è ancora la scelta giusta, come mantenerlo funzionante e come abbandonarlo in modo pulito. Questa guida copre tutti e tre gli aspetti.

Quando CocoaPods è ancora la scelta giusta

Rimani su, o scegli, CocoaPods se una di queste condizioni è vera:

• Un plugin di cui hai bisogno non ha Package.swift. In un progetto SPM, CLI avvisa che “Alcuni plugin Capacitor installati non sono compatibili con SPM” ed esclude quel plugin, causando un errore a runtime “plugin is not implemented”.
• Un vendor SDK è distribuito solo come pod. Alcuni SDK per analytics, pagamenti e identità vengono ancora forniti solo tramite CocoaPods, oppure includono un xcframework che dovresti incapsulare tu stesso.
• Un plugin Cordova dipende dai pod. Capacitor genera un pacchetto Swift per i plugin Cordova nei progetti SPM, ma quelli complessi con <podspec> dipendenze tendono a funzionare meglio con CocoaPods.
• Dipendi dai subspecs di podspec per scegliere le varianti SDK. SPM ha ora i package traits, e Capacitor li supporta in modo sperimentale da CLI 8.3 (vedi Caratteristiche dei pacchetti SPM in Capacitor), ma il plugin deve prima definire i traits.
• Un grande progetto Xcode personalizzato dove una migrazione non vale il rischio in questo ciclo di rilascio.

Le collisioni di identità dei pacchetti erano un'altra ragione. Da CLI 8.4 puoi evitarle in SPM con experimental.ios.spm.packageOptions (symlink oppure moduleAliases) nella tua configurazione Capacitor.

Se nessuno di questi casi si applica, usa SPM. Non richiede toolchain Ruby, né Podfile, né .xcworkspace.

CocoaPods vs SPM in Capacitor 8

Installa CocoaPods

Scegli un approccio e usalo ovunque, incluso in CI.

Homebrew (il più semplice per un singolo sviluppatore):

brew install cocoapods
pod --version

Bundler (fissa la versione per l'intero team, consigliato per CI). Crea un Gemfile nella root del progetto o in ios/App:

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

bundle install

Quando Capacitor CLI trova un Gemfile che menziona CocoaPods, esegue bundle exec pod install invece di pod install. Se pod si trova in una posizione insolita, imposta CAPACITOR_COCOAPODS_PATH sul binario.

Crea un'app Capacitor 8 con CocoaPods

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

cap open ios apre App.xcworkspace. Compila sempre dal workspace. Apri App.xcodeproj ti dà direttamente No such module 'Capacitor'.

Il Podfile, spiegato

Questo è il Podfile generato da Capacitor 8:

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

Cosa puoi e non puoi modificare:

• def capacitor_pods ... end appartiene a CLI. A ogni sync sostituisce l'intero blocco con una pod riga per plugin, che punta alla cartella del plugin in node_modules. Qualsiasi cosa aggiungi all'interno viene persa.
• Aggiungi i tuoi pod sotto target 'App', dopo che capacitor_pods.
• assertDeploymentTarget alza a 15.0 qualsiasi pod con deployment target inferiore a 15.0, evitando i warning di Xcode su target non supportati. Tienilo e aggiungi il tuo post_install logica all'interno dello stesso blocco.
• platform :ios deve essere almeno 15.0 per Capacitor 8.

Esempio con un pod extra e una correzione delle impostazioni di build:

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

Il loop disabilita la firma code per i target dei bundle di risorse. Corregge Signing for "X" requires a development team sui pod che includono bundle di risorse. Aggiungilo solo se riscontri quell'errore.

Comandi quotidiani

# 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 esegue anche xcodebuild clean sul progetto dopo pod install, quindi non serve una pulizia manuale dopo aver aggiunto i plugin.

Commit Podfile e Podfile.lock. Non fare commit di ios/App/Pods/. Viene rigenerato da pod install.

Passare da SPM a CocoaPods in un'app esistente

Non esiste un comando di migrazione inversa. Fallo a mano:

1. Commit, poi copia ios/ in un posto sicuro.
2. Elimina ios/.
3. Esegui bunx cap add ios --packagemanager CocoaPods.
4. Riapplica le modifiche native: Info.plist chiavi, entitlements e capability, team di firma, bundle identifier, icone e asset splash, URL scheme, estensioni (widget, notification service) e qualsiasi Swift personalizzato in AppDelegate.
5. bunx cap sync ios e build.

Fare il diff tra le cartelle ios/App/App Le cartelle sono il modo più rapido per individuare ciò che hai trascurato.

Correggere gli errori comuni di CocoaPods

CocoaPods could not find compatible versions for pod "X". O il tuo spec repo locale è obsoleto, oppure due pod richiedono versioni incompatibili. Esegui pod install --repo-update nella ios/App. Se continua a fallire, leggi la catena di dipendenze nell'errore, individua il plugin con il pin rigido, aggiornalo o modifica il suo podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Il Pods la cartella non corrisponde al lock file, solitamente dopo un cambio di branch. Esegui bunx cap sync ios.

[!] Unable to find a specification for 'X'. La cache del repo spec è obsoleta o il nome del pod è errato. Esegui pod repo update.

Unable to find compatibility version string for object version '70' (o 77). Il tuo progetto Xcode usa un formato più recente di quello supportato dalla gem CocoaPods/xcodeproj. Aggiorna CocoaPods all'ultima release. Se non puoi, fai il backup di project.pbxproj e imposta objectVersion a un valore supportato da CocoaPods.

Sandbox: rsync(...) deny(1) file-write-create. Il sandboxing degli script utente di Xcode blocca lo script di embed di CocoaPods. In Impostazioni di Build, imposta Sandboxing degli User Script (ENABLE_USER_SCRIPT_SANDBOXING) a No per il target App.

No such module 'Capacitor'. Hai aperto App.xcodeproj. Apri App.xcworkspace, oppure esegui bunx cap open ios.

pod: command not found in CI. Installa CocoaPods nel job, oppure usa Bundler con un vendor/bundle. Senza di esso, CLI registra “Skipping pod install because CocoaPods is not installed” e la build fallisce in seguito.

Altri errori di build iOS sono trattati nel Guida alla risoluzione problemi iOS di Capacitor.

La data di sola lettura del trunk di CocoaPods

I maintainer di CocoaPods hanno annunciato che trunk, il repository centrale delle spec, diventerà di sola lettura il 2 dicembre 2026, dopo una prova a inizio novembre 2026. Ecco cosa significa per un'app Capacitor:

• Le build esistenti continuano a funzionare. Ogni podspec pubblicato resta disponibile.
• Nessuna nuova versione tramite trunk. Gli SDK che ottieni da trunk (Firebase, Google ML Kit, SDK di vendor) smetteranno di ricevere aggiornamenti lì. Le patch di sicurezza e il supporto per il nuovo iOS SDK arriveranno solo tramite SPM o altri canali.
• I plugin Capacitor non sono direttamente interessati. Vengono installati da npm e referenziati tramite :path nel Podfile. Le loro dipendenze pod transitive sì.

Considera CocoaPods un ponte. Elenca quale dipendenza ti tiene su di esso e rivaluta quando quella dipendenza aggiungerà il supporto SPM.

Abbandonare CocoaPods

Quando sei pronto:

bunx cap spm-migration-assistant

Esegue pod deintegrate, removes the Podfile, Podfile.lock e App.xcworkspace, crea CapApp-SPM, e scrive un debug.xcconfig. Poi aggiungi CapApp-SPM come pacchetto locale in Xcode e imposta debug.xcconfig come file di configurazione Debug. La guida completa è in come migrare la tua app Capacitor a SPM, e i compromessi sono trattati in SPM vs CocoaPods per Capacitor.

Gli autori di plugin che devono aggiungere il supporto SPM dovrebbero leggere migrare un plugin Capacitor a SPM.

Se gestire Ruby, CocoaPods e le versioni di Xcode sulle macchine di build è la parte più difficile, Build Capgo esegue il build di progetti CocoaPods e SPM nel cloud con l'attuale versione di Xcode.