Comment utiliser CocoaPods avec Capacitor 8 (et quand ne pas le faire)

Pour utiliser CocoaPods avec Capacitor 8, créez la plateforme iOS avec bunx cap add ios --packagemanager CocoaPodsInstallez CocoaPods (Homebrew ou un fichier Gemfile avec Bundler), et laissez bunx cap sync ios gérer le fichier Podfile et exécutez pod install.Capacitor 8 continue à supporter CocoaPods. Seule la valeur par défaut pour les nouveaux projets a été changée pour le gestionnaire de packages Swift.

CocoaPods n'est plus la direction à long terme, et son tronc devient lecture seule le 2 décembre 2026. La vraie question est donc quand il est encore la bonne option, comment le conserver en fonction et comment le quitter proprement. Cette guide couvre les trois cas.

Quand CocoaPods est encore la bonne option

Restez sur CocoaPods ou choisissez-le lorsque l'une de ces conditions est vraie :

• Un plugin dont vous avez besoin n'existe pas Package.swift. Dans un projet SPM, CLI affiche « Certains plugins Capacitor installés ne sont pas compatibles avec SPM » et laisse ce plugin de côté, ce qui entraîne une erreur à l'exécution avec « plugin non implémenté ».
• Un fournisseur SDK est distribué uniquement sous forme de pod. Certains SDK d'analytique, de paiement et d'identité livrent toujours uniquement CocoaPods, ou livrent un xcframework que vous devrez envelopper vous-même.
• Un plugin Cordova repose sur des pods. Capacitor génère un package Swift pour les plugins Cordova dans les projets SPM, mais les complexes avec <podspec> Vous dépendez des sous-espèces de podspec
• Vous vous appuyez sur les sous spécifications podspec. Pour choisir des variantes SDK. SPM dispose désormais de traits de package, et Capacitor les prend en charge expérimentalement depuis CLI 8.3 (voir Les caractéristiques de package SPM dans CapacitorSPM des traits de package dans __CAPGO_KEEP_0__
• Un grand projet Xcode personnalisé dans ce cycle de mise à jour, une migration n'en vaut pas la peine.

Depuis CLI 8.4, les collisions d'identité de package ne constituent plus un problème. Vous pouvez les contourner avec SPM. experimental.ios.spm.packageOptions (symlink or moduleAliases) dans votre Capacitor config.

Si aucune de ces options ne s'applique, utilisez SPM. Il n'a besoin d'aucun outil Ruby, ni de fichier Podfile. .xcworkspace.

CocoaPods vs SPM in Capacitor 8

Installer CocoaPods

Utilisez une approche et utilisez-la partout, y compris dans la CI.

Homebrew (la plus simple pour un développeur):

brew install cocoapods
pod --version

Bundler (fixe la version pour l'ensemble de l'équipe, recommandé pour la CI). Créez un Gemfile dans le répertoire du projet ou dans ios/App:

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

bundle install

Lorsque le Capacitor CLI trouve un Gemfile mentionne CocoaPods, il s'exécute bundle exec pod install au lieu de pod install. Si pod vit quelque part inhabituel, définissez CAPACITOR_COCOAPODS_PATH sur le binaire.

Créez une application Capacitor 8 avec CocoaPods

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

cap open ios s'ouvre App.xcworkspaceToujours construisez à partir du workspace. Ouvrez. App.xcodeproj directement vous donne No such module 'Capacitor'.

Le Podfile, expliqué

Ceci est le Podfile Capacitor 8 génère :

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

Ce que vous pouvez et ne pouvez pas toucher :

• def capacitor_pods ... end fait partie de CLI. On chaque synchronisation, il remplace la totalité du bloc par un. pod Tout ce que vous ajoutez à l'intérieur est perdu. node_modulesAjoutez vos propres pods sous
• Ajoutez vos propres pods sous target 'App', after capacitor_pods.
• assertDeploymentTarget raises any pod with a deployment target below 15.0 up to 15.0, which avoids Xcode warnings about unsupported targets. Keep it, and add your own post_install doit être au moins 15.0 pour __CAPGO_KEEP_0__ 8.
• platform :ios doit être d'au moins 15.0 pour 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

La boucle désactive la signature code pour les cibles de bundle de ressources. Elle corrige Signing for "X" requires a development team ajoutez-l’uniquement si vous rencontrez cette erreur.

Commandes quotidiennes

# 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 exécute également xcodebuild clean sur le projet après pod installAinsi, vous n'avez pas besoin d'une nettoyage manuel après l'ajout de plugins.

Commit Podfile et Podfile.lockN'ajoutez pas. ios/App/Pods/. N'effectuez pas de commit pod install.

Passer d'une application existante à SPM vers CocoaPods

Passer d'une application existante de SPM à CocoaPods

1. Commitez, puis copiez ios/ Commit, puis copiez-le
2. Supprimer ios/.
3. Démarrez bunx cap add ios --packagemanager CocoaPods.
4. Reappliquer les modifications natives : Info.plist Clés, droits et capacités, équipe de signature, identifiant de l'application, icônes et assets de splash, schémas de URL, extensions (widgets, service de notification), et tout code Swift personnalisé. AppDelegate.
5. bunx cap sync ios et construisez.

Comparer les anciens et les nouveaux ios/App/App Les dossiers sont la meilleure façon de capturer ce que vous avez manqué.

Corriger les erreurs courantes de CocoaPods

CocoaPods could not find compatible versions for pod "X". Votre répertoire local de spécifications est obsolète ou deux pods nécessitent des versions incompatibles. Exécutez pod install --repo-update en ios/AppSi cela continue à échouer, lisez la chaîne de dépendance dans l'erreur, trouvez le plugin avec la fixation stricte, le mettez à jour ou corrigez son podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Le Pods folder ne correspond pas au fichier de verrouillage, généralement après avoir changé de branch. Exécutez bunx cap sync ios.

[!] Unable to find a specification for 'X'. Le cache du dépôt de spécifications est périmé ou le nom du pod est incorrect. Exécutez pod repo update.

Unable to find compatibility version string for object version '70' ou 77Votre projet Xcode utilise une version plus récente que le gem CocoaPods/xcodeproj ne comprend. Mettez à jour CocoaPods vers la dernière version. Si vous ne pouvez pas, sauvegardez project.pbxproj et définissez objectVersion à une valeur que CocoaPods prend en charge.

Sandbox: rsync(...) deny(1) file-write-create. Le sandbox de script de l'utilisateur Xcode bloque le script d'embed CocoaPods. Réglages de construction, définissez Sandboxing des scripts utilisateur (ENABLE_USER_SCRIPT_SANDBOXING) à No pas pour la cible App.

No such module 'Capacitor'. Vous avez ouvert App.xcodeproj. Ouvrez App.xcworkspace, ou exécutez bunx cap open ios.

pod: command not found en CI. Installez CocoaPods dans le job, ou utilisez Bundler avec un cache vendor/bundle. Sans cela, les CLI journaux affichent « Étape de pod sautée car CocoaPods n'est pas installé » et la construction échoue ensuite.

Plus d'erreurs de construction iOS sont couvertes dans le Guide de dépannage iOS de Capacitor.

La date de lecture seule du tronc 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:

• Les constructions existantes continuent de fonctionner. Tous les podspecs publiés restent disponibles.
• Aucune nouvelle version par le tronc. Les SDK que vous récupérez du tronc (Firebase, Google ML Kit, SDKs de fournisseur) cessent d'y recevoir des mises à jour. Les correctifs de sécurité et le support de SDK pour iOS ne seront disponibles que par le biais de SPM ou d'autres canaux.
• Les plugins Capacitor eux-mêmes ne sont pas directement affectés. Ils sont installés à partir de npm et référencés par :path en fichier Podfile. Les dépendances de pods transitoires sont.

Traitez CocoaPods comme un pont. Indiquez quelle dépendance vous maintient dessus, et révisitez lorsque cette dépendance ajoute un support SPM.

Se débarrasser de CocoaPods

Quand vous êtes prêt :

bunx cap spm-migration-assistant

Il fonctionne pod deintegrateet supprime le Podfile, Podfile.lock et App.xcworkspace, crée CapApp-SPM, et écrit un debug.xcconfigVous ajoutez ensuite CapApp-SPM comme un package local dans Xcode et définissez debug.xcconfig comme fichier de configuration de débogage. La procédure complète est décrite dans comment migrer votre Capacitor application vers SPM, et les compromis sont abordés dans SPM vs CocoaPods pour Capacitor.

Auteurs de plugins qui doivent ajouter le support SPM devraient lire migrer un Capacitor plugin vers SPM.

Si gérer les versions de Ruby, CocoaPods et Xcode sur les machines de build est le plus pénible. Capgo Build Construire les projets CocoaPods et SPM dans le cloud sur la dernière version d'Xcode.