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 CocoaPods, installez CocoaPods (via Homebrew ou un Gemfile avec Bundler) et laissez bunx cap sync ios gérer le Podfile et exécuter pod install. Capacitor 8 prend toujours entièrement en charge CocoaPods. Seule la valeur par défaut pour les nouveaux projets a changé au profit de Swift Package Manager.

CocoaPods n’est plus la direction à long terme, et son trunk passera en lecture seule le 2 décembre 2026. La vraie question est donc de savoir quand il reste le bon choix, comment le maintenir fonctionnel et comment s’en débarrasser proprement. Ce guide couvre ces trois aspects.

Quand CocoaPods reste le bon choix

Restez sur, ou choisissez, CocoaPods si l’une de ces conditions est vraie :

• Un plugin dont vous avez besoin n’a pas de Package.swift. Dans un projet SPM, CLI émet un avertissement « Some installed Capacitor plugins are not compatible with SPM » et exclut ce plugin, ce qui provoque une erreur d’exécution « plugin is not implemented ».
• Un fournisseur SDK est distribué uniquement sous forme de pod. Certains SDK d’analytics, de paiement et d’identité ne sont toujours disponibles qu’en CocoaPods, ou fournissent un xcframework qu’il faut encapsuler soi-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 plugins complexes avec <podspec> des dépendances ont tendance à mieux fonctionner avec CocoaPods.
• Vous vous appuyez sur les subspecs de podspec pour choisir les variantes SDK. SPM dispose désormais de traits de package, et Capacitor les prend en charge de façon expérimentale depuis CLI 8.3 (voir Les traits de package SPM dans Capacitor), mais le plugin doit d’abord définir ces traits.
• Un projet Xcode volumineux et personnalisé où une migration ne vaut pas le risque pour ce cycle de release.

Les collisions d’identité de package étaient une autre raison. Depuis CLI 8.4, vous pouvez les contourner dans SPM avec experimental.ios.spm.packageOptions (symlink ou moduleAliases) dans votre configuration Capacitor.

Si aucun de ces cas ne s’applique, utilisez SPM. Pas besoin de toolchain Ruby, ni de Podfile, ni de .xcworkspace.

CocoaPods vs SPM dans Capacitor 8

Installer CocoaPods

Choisissez une approche et utilisez-la partout, y compris en CI.

Homebrew (le plus simple pour un seul développeur) :

brew install cocoapods
pod --version

Bundler (verrouille la version pour toute l’équipe, recommandé pour la CI). Créez un Gemfile à la racine du projet ou dans ios/App:

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

bundle install

Lorsque Capacitor CLI détecte un Gemfile qui mentionne CocoaPods, il exécute bundle exec pod install au lieu de pod install. Si pod se trouve à un emplacement inhabituel, définissez CAPACITOR_COCOAPODS_PATH sur le binaire.

Créer 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 ouvre App.xcworkspace. Compilez toujours depuis le workspace. Ouvrir App.xcodeproj vous donne directement No such module 'Capacitor'.

Le Podfile expliqué

Voici le Podfile généré par 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

Ce que vous pouvez et ne pouvez pas modifier :

• def capacitor_pods ... end appartient à CLI. À chaque synchronisation, il remplace tout le bloc par une pod ligne par plugin, pointant vers le dossier du plugin dans node_modules. Tout ce que vous ajoutez à l’intérieur est perdu.
• Ajoutez vos propres pods sous target 'App', après capacitor_pods.
• assertDeploymentTarget monte tout pod dont la cible de déploiement est inférieure à 15.0 à 15.0, ce qui évite les avertissements Xcode sur les cibles non prises en charge. Conservez-l’et ajoutez votre propre post_install logique dans le même bloc.
• platform :ios doit être au moins 15.0 pour Capacitor 8.

Exemple avec un pod supplémentaire et une correction de 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

La boucle désactive la signature code pour les cibles de bundle de ressources. Elle corrige Signing for "X" requires a development team sur les pods qui livrent des bundles de ressources. N’ajoutez-le que si vous rencontrez cette erreur.

Commandes du quotidien

# 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 install, vous n’avez donc pas besoin d’un nettoyage manuel après l’ajout de plugins.

Commit Podfile et Podfile.lock. Ne committez pas ios/App/Pods/. Il est régénéré par pod install.

Passer une application existante de SPM à CocoaPods

Il n’existe pas de commande de migration inverse. Faites-le manuellement :

1. Commit, puis copier ios/ en lieu sûr.
2. Supprimer ios/.
3. Exécutez bunx cap add ios --packagemanager CocoaPods.
4. Réappliquez les changements natifs : Info.plist clés, entitlements et capabilities, équipe de signature, bundle identifier, icônes d'app et assets de splash, URL schemes, extensions (widgets, notification service), et tout code Swift personnalisé dans AppDelegate.
5. bunx cap sync ios et compilez.

Comparer l'ancien et le nouveau ios/App/App dossiers est le moyen le plus rapide de repérer ce que vous avez oublié.

Corriger les erreurs CocoaPods courantes

CocoaPods could not find compatible versions for pod "X". Soit votre repo de specs local est obsolète, soit deux pods nécessitent des versions incompatibles. Lancez pod install --repo-update dans ios/App. Si cela échoue encore, lisez la chaîne de dépendances dans l'erreur, trouvez le plugin avec le verrouillage strict, mettez-l’à jour ou modifier son podspec.

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

[!] Unable to find a specification for 'X'. Le cache du spec repo est obsolète ou le nom du pod est incorrect. Exécutez pod repo update.

Unable to find compatibility version string for object version '70' (ou 77). Votre projet Xcode utilise un format plus récent que ce que votre gem CocoaPods/xcodeproj prend en charge. Mettez à jour CocoaPods vers la dernière release. Si ce n’est pas possible, sauvegardez project.pbxproj et configurez objectVersion à une valeur prise en charge par votre CocoaPods.

Sandbox: rsync(...) deny(1) file-write-create. Le sandbox de scripts utilisateur d’Xcode bloque le script d’intégration de CocoaPods. Dans Paramètres de build, définissez Sandboxing des scripts utilisateur (ENABLE_USER_SCRIPT_SANDBOXING) à Non 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 dans votre CI. Installez CocoaPods dans le job, ou utilisez Bundler avec un vendor/bundle. Sans cela, les logs CLI affichent « Skipping pod install because CocoaPods is not installed » et le build échoue ensuite.

D'autres erreurs de build iOS sont couvertes dans guide de dépannage iOS de Capacitor.

La date de lecture seule du trunk CocoaPods

Les mainteneurs de CocoaPods ont annoncé que trunk, le dépôt central de spécifications, passera en lecture seule le 2 décembre 2026, après une phase de test début novembre 2026. Ce que cela implique pour une app Capacitor :

• Les builds existants continuent de fonctionner. Chaque podspec publié reste disponible.
• Aucune nouvelle version via trunk. Les SDK récupérés depuis trunk (Firebase, Google ML Kit, SDK de fournisseurs) n'y recevront plus de mises à jour. Les correctifs de sécurité et la prise en charge des nouvelles versions d'iOS SDK ne seront plus déployés que via SPM ou d'autres canaux.
• Les plugins Capacitor ne sont pas directement affectés. Ils sont installés depuis npm et référencés par :path dans le Podfile. En revanche, leurs dépendances pod transitives le sont.

Considérez CocoaPods comme un pont. Identifiez la dépendance qui vous y maintient, et réévaluez la situation dès qu'elle prendra en charge SPM.

Se passer de CocoaPods

Quand vous êtes prêt :

bunx cap spm-migration-assistant

Il s’exécute pod deintegrate, supprime le Podfile, Podfile.lock et App.xcworkspace, crée CapApp-SPM, et écrit un debug.xcconfig. Vous ajoutez ensuite CapApp-SPM en tant que package local dans Xcode et définissez debug.xcconfig comme fichier de configuration Debug. Le guide complet est dans comment migrer votre app Capacitor vers SPM, et les compromis sont abordés dans SPM vs CocoaPods pour Capacitor.

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

Si gérer les versions de Ruby, CocoaPods et Xcode sur les machines de build est le point pénible, Build Capgo compile les projets CocoaPods et SPM dans le cloud avec Xcode à jour.