Come utilizzare CocoaPods con Capacitor 8 (e quando non farlo)

To use CocoaPods with Capacitor 8, create the iOS platform with bunx cap add ios --packagemanager CocoaPods, installa CocoaPods (Homebrew o un Gemfile con Bundler), e lascia bunx cap sync ios gestire il file Podfile e esegui pod install.Capacitor 8 continua a supportare CocoaPods. È cambiata solo la configurazione predefinita per i nuovi progetti, che ora utilizza il gestore di pacchetti Swift.

CocoaPods non è più la direzione a lungo termine, e il suo tronco diventa lettura solo il 2 dicembre 2026. Quindi la vera domanda è quando è ancora la scelta giusta, come mantenerlo funzionante e come lasciarlo pulitamente. Questa guida copre tutte e tre le cose.

Quando CocoaPods è ancora la scelta giusta

Resta su, o scegli, CocoaPods quando è vero uno di questi:

• A un plugin che hai bisogno manca Package.swift. In un progetto SPM il CLI avverte “Alcuni plugin Capacitor installati non sono compatibili con SPM” e lascia fuori quel plugin, quindi fallisce all'esecuzione con “plugin non implementato”.
• Un vendor SDK è distribuito solo come un pod. Alcuni SDK di analytics, pagamento e identità ancora spediscono solo CocoaPods, o spediscono un xcframework che dovresti avvolgere tu stesso.
• Un plugin Cordova dipende dai pods. Capacitor genera un pacchetto Swift per i plugin Cordova nei progetti SPM, ma quelli complessi con <podspec> dipendenze tendono a funzionare meglio con CocoaPods.
• Riscontri dipendenze da podspec subspecs per scegliere SDK varianti. SPM ha ora caratteristiche dei pacchetti e Capacitor le supporta sperimentalmente dal CLI 8.3 (vedi caratteristiche dei pacchetti SPM in Capacitor), ma il plugin deve definire le caratteristiche prima.
• Un grande progetto Xcode personalizzato ove il rischio in questo ciclo di rilascio.

Le collisioni di identità dei pacchetti utilizzavano a essere un altro motivo. Dal CLI 8.4 puoi lavorare intorno a loro con SPM experimental.ios.spm.packageOptions (symlink o moduleAliases) nella tua configurazione Capacitor.

Se nessuna di queste si applica, utilizza SPM. Non richiede alcun toolchain Ruby, nessun file Podfile e nessun .xcworkspace.

CocoaPods vs SPM in Capacitor 8

Installa CocoaPods

Scegli un approccio e utilizzalo in ogni momento, incluso nella CI.

Homebrew (più semplice per un solo sviluppatore):

brew install cocoapods
pod --version

Bundler (blocca la versione per l'intera squadra, consigliato per la CI). Crea un Gemfile nella cartella root del progetto o in ios/App:

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

bundle install

Quando il Capacitor CLI trova un Gemfile che menziona CocoaPods, esegue bundle exec pod install al posto di pod installSe pod risiede in un luogo insolito, impostalo CAPACITOR_COCOAPODS_PATH alla versione binaria.

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.xcworkspaceCostruisci sempre dal workspace. L'apertura App.xcodeproj ti dà direttamente No such module 'Capacitor'.

Il file Podfile, spiegato

Questo è il file Podfile Capacitor 8 che 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

Cosa puoi e cosa non puoi toccare:

• def capacitor_pods ... end appartiene a CLI. On ogni sincronizzazione sostituisce l'intero blocco con uno pod Tutto ciò che aggiungi all'interno viene perso. node_modulesTutto ciò che aggiungi all'interno viene perso.
• Aggiungi i tuoi propri pods sotto target 'App', dopo capacitor_pods.
• assertDeploymentTarget solleva qualsiasi pod con un target di distribuzione inferiore a 15.0 fino a 15.0, il che evita le avvertenze di Xcode sui target non supportati. Tienilo e aggiungi il tuo proprio post_install logica all'interno della stessa blocco.
• platform :ios deve essere almeno 15.0 per Capacitor 8.

Esempio con un pod aggiuntivo e una correzione di impostazione 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

Lo ciclo disabilita la firma code per i target dei bundle di risorse. Corregge Signing for "X" requires a development team su pods che inviano bundle di risorse. Aggiungilo solo se incontri quell'errore.

Comandi di tutti i giorni

# 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 si esegue xcodebuild clean dopo il progetto pod install, quindi non è necessario un pulizia manuale dopo l'aggiunta di plugin.

Commit Podfile e Podfile.lockNon commettere ios/App/Pods/È regenerato da pod install.

Passare un'app esistente da SPM a CocoaPods

Non esiste un comando di migrazione inversa. Fai manualmente:

1. Commit, quindi copia ios/ in un posto sicuro.
2. Elimina ios/.
3. Esegui bunx cap add ios --packagemanager CocoaPods.
4. Ripristina le modifiche native: Info.plist chiavi, autorizzazioni e capacità, team di firma, identificatore del bundle, icone e asset di splash, schemi di URL, estensioni (widget, servizio di notifica) e qualsiasi Swift personalizzato AppDelegate.
5. bunx cap sync ios e costruisci.

La differenza tra l'antico e il nuovo ios/App/App I folderi è il modo più veloce per raccogliere ciò che ti sei perso.

Risolvere gli errori comuni di CocoaPods

CocoaPods could not find compatible versions for pod "X". O il tuo repository spec locale è datato o due pods richiedono versioni incompatibili. Esegui pod install --repo-update in ios/App. Se non riesce ancora, leggi la catena di dipendenza nell'errore, trova il plugin con la pin rigida, aggiornalo o patch il suo podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Il Pods cartella non corrisponde al file di blocco, di solito dopo aver cambiato rami. Esegui bunx cap sync ios.

[!] Unable to find a specification for 'X'. Il repository spec è datato o il nome del pod è sbagliato. Esegui pod repo update.

Unable to find compatibility version string for object version '70' o 77Il tuo progetto Xcode utilizza una versione più recente del formato rispetto al gem CocoaPods/xcodeproj che comprende. Aggiorna CocoaPods alla versione più recente. Se non puoi, salva una copia project.pbxproj e impostalo objectVersion su un valore che CocoaPods supporta.

Sandbox: rsync(...) deny(1) file-write-create. Xcode's sandboxing del script di CocoaPods blocca lo script di embed. Impostazioni di compilazioneimposta Sandboxing degli script utente (ENABLE_USER_SCRIPT_SANDBOXING) su No per il target App.

No such module 'Capacitor'. Hai aperto App.xcodeprojOpen App.xcworkspace, o esegui bunx cap open ios.

pod: command not found in CI. Installare CocoaPods nel job, o utilizzare Bundler con un cache vendor/bundleSenza di esso, i CLI log ‘Ignorando l'installazione del pod perché CocoaPods non è installato’ e il build fallisce in seguito.

Maggiori errori di compilazione iOS sono trattati nel Capacitor iOS troubleshooting guide.

La data di sola lettura del tronco di CocoaPods

The CocoaPods maintainers announced that trunk, the central spec repository, becomes read-only on December 2, 2026, after a test run in early November 2026. What that means for a Capacitor app:

• Ogni spec di pod pubblicato rimane disponibile. Non sono disponibili nuove versioni attraverso la coda.
• Nessuna nuova versione attraverso il tronco. SDKs you pull from trunk (Firebase, Google ML Kit, vendor SDKs) stop getting updates there. Security fixes and new iOS SDK support will only ship through SPM or other channels.
• I plugin Capacitor non sono direttamente colpiti. Sono installati da npm e si riferiscono a :path nel file Podfile. Le loro dipendenze pod transitive sono.

Tratta CocoaPods come un ponte. Elencare quale dipendenza ti tiene su di esso, e riprendi quando quella dipendenza aggiunge il supporto SPM.

Spostarsi da CocoaPods

Quando sei pronto:

bunx cap spm-migration-assistant

Esegue pod deintegrate, rimuove il Podfile, Podfile.lock e App.xcworkspacecrea CapApp-SPM, e scrive un debug.xcconfige poi aggiungi CapApp-SPM come pacchetto locale in Xcode e impostare debug.xcconfig come il file di configurazione Debug. La guida completa è in come migrare la tua Capacitor app a SPM, e i vantaggi sono trattati in SPM vs CocoaPods per Capacitor.

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

Se il gestire Ruby, CocoaPods e versioni di Xcode sulle macchine di build è la parte dolorosa, Capgo Build costruisce progetti CocoaPods e SPM in cloud con l'ultima versione di Xcode.