CocoaPods mit Capacitor 8 nutzen (und wann nicht)

Um CocoaPods mit Capacitor 8 zu nutzen, erstellen Sie die iOS-Plattform mit bunx cap add ios --packagemanager CocoaPods, installieren Sie CocoaPods (Homebrew oder ein Gemfile mit Bundler) und lassen Sie bunx cap sync ios die Podfile verwalten und ausführen pod install. Capacitor 8 unterstützt CocoaPods weiterhin vollumfänglich. Nur der Standard für neue Projekte wurde auf Swift Package Manager umgestellt.

CocoaPods ist nicht mehr die langfristige Richtung; der Trunk wird am 2. Dezember 2026 schreibgeschützt. Die eigentliche Frage ist also: Wann ist es noch die richtige Wahl, wie lässt es sich am Laufen halten und wie migriert man sauber davon? Dieser Guide deckt alle drei Punkte ab.

Wann CocoaPods noch die richtige Wahl ist

Bleib bei CocoaPods oder wähle es, wenn einer dieser Punkte zutrifft:

• Ein benötigtes Plugin hat keinen Package.swift. In einem SPM-Projekt warnt CLI mit „Some installed Capacitor plugins are not compatible with SPM“ und lässt das Plugin weg, was zu einem Runtime-Fehler „plugin is not implemented“ führt.
• Ein Vendor SDK wird nur als Pod ausgeliefert. Einige Analytics-, Payment- und Identity-SDKs werden nur mit CocoaPods oder als xcframework bereitgestellt, das man selbst wrappen müsste.
• Ein Cordova-Plugin ist auf Pods angewiesen. Capacitor generiert zwar Swift Packages für Cordova-Plugins in SPM-Projekten, aber komplexe Plugins mit <podspec> Abhängigkeiten funktionieren tendenziell besser mit CocoaPods.
• Du verlässt dich auf Podspec-Subspecs, um SDK-Varianten zu wählen. SPM hat jetzt Package Traits, und Capacitor unterstützt sie seit CLI 8.3 experimentell (siehe SPM Package Traits in Capacitor), aber das Plugin muss die Traits zuerst definieren.
• Ein großes, angepasstes Xcode-Projekt , bei dem eine Migration in diesem Release-Zyklus das Risiko nicht wert ist.

Package-Identity-Kollisionen waren früher ein weiterer Grund. Seit CLI 8.4 kannst du sie in SPM umgehen mit experimental.ios.spm.packageOptions (symlink oder moduleAliases) in deiner Capacitor-Config.

Falls nichts davon zutrifft, nutze SPM. Es braucht keine Ruby-Toolchain, keine Podfile und kein .xcworkspace.

CocoaPods vs. SPM in Capacitor 8

CocoaPods installieren

Wähle einen Ansatz und nutze ihn überall, auch in der CI.

Homebrew (am einfachsten für Einzelentwickler):

brew install cocoapods
pod --version

Bundler (fixiert die Version für das ganze Team, empfohlen für CI). Erstelle eine Gemfile im Projekt-Root oder in ios/App:

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

bundle install

Wenn die Capacitor CLI ein Podfile Gemfile findet, das CocoaPods erwähnt, führt sie aus bundle exec pod install anstatt pod install. Wenn pod an einem ungewöhnlichen Ort liegt, setze CAPACITOR_COCOAPODS_PATH auf die Binärdatei.

Erstelle eine Capacitor 8 App mit CocoaPods

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

cap open ios öffnet App.xcworkspace. Baue immer aus dem Workspace. Das direkte Öffnen von App.xcodeproj ermöglicht dir direkt No such module 'Capacitor'.

Das Podfile erklärt

Das ist das Podfile, das Capacitor 8 generiert:

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

Was du ändern kannst und was nicht:

• def capacitor_pods ... end gehört zum CLI. Bei jedem Sync wird der gesamte Block durch eine pod Zeile pro Plugin ersetzt, die auf den Plugin-Ordner in node_modules. Alles, was du dort hinzufügst, geht verloren.
• Füge deine eigenen Pods unter target 'App'hinzu, nach capacitor_pods.
• assertDeploymentTarget erhöht jeden Pod mit einem Deployment Target unter 15.0 auf 15.0, um Xcode-Warnungen zu vermeiden. Behalte dies und füge deine eigenen post_install Logik innerhalb desselben Blocks hinzu.
• platform :ios muss mindestens 15.0 für Capacitor 8 sein.

Beispiel mit einem extra Pod und einem 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

Die Schleife deaktiviert das code Signing für Resource Bundle Targets. Es behebt Signing for "X" requires a development team bei Pods, die Resource Bundles enthalten. Füge es nur hinzu, wenn dieser Fehler auftritt.

Tägliche Commands

# 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 also runs xcodebuild clean im Projekt, nachdem pod install, sodass nach dem Hinzufügen von Plugins kein manuelles Clean nötig ist.

Commit Podfile und Podfile.lock. Committe nicht ios/App/Pods/. Es wird regeneriert durch pod install.

Eine bestehende App von SPM auf CocoaPods umstellen

Es gibt keinen Befehl für die Rückmigration. Mach es manuell:

1. Commit, dann kopieren ios/ an einem sicheren Ort.
2. Löschen ios/.
3. Ausführen bunx cap add ios --packagemanager CocoaPods.
4. Native Änderungen erneut anwenden: Info.plist Keys, Entitlements und Capabilities, Signing Team, Bundle Identifier, App-Icons und Splash-Assets, URL-Schemes, Extensions (Widgets, Notification Service) sowie jeglicher Custom Swift Code in AppDelegate.
5. bunx cap sync ios und builden.

Vergleich von Alt und Neu ios/App/App Ordner sind der schnellste Weg, um nichts zu übersehen.

Häufige CocoaPods-Fehler beheben

CocoaPods could not find compatible versions for pod "X". Entweder ist dein lokales Spec-Repo veraltet oder zwei Pods benötigen inkompatible Versionen. Führe pod install --repo-update in ios/Appaus. Falls es weiterhin fehlschlägt, lies die Dependency Chain in der Fehlermeldung, finde das Plugin mit dem strikten Pin und aktualisiere es oder die podspec patchen.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Der Pods Ordner stimmt nicht mit der Lock-Datei überein, meist nach einem Branch-Wechsel. Führe aus: bunx cap sync ios.

[!] Unable to find a specification for 'X'. Der Spec-Repo-Cache ist veraltet oder der Pod-Name ist falsch. Führe aus: pod repo update.

Unable to find compatibility version string for object version '70' (oder 77). Dein Xcode-Projekt nutzt ein neueres Format, als dein CocoaPods/xcodeproj gem versteht. Aktualisiere CocoaPods auf die neueste Version. Falls das nicht geht, sichere project.pbxproj und setze objectVersion auf einen Wert, den dein CocoaPods unterstützt.

Sandbox: rsync(...) deny(1) file-write-create. Xcode User Script Sandboxing blockiert das CocoaPods Embed-Script. In Build-Einstellungen, setzen User-Script-Sandboxing (ENABLE_USER_SCRIPT_SANDBOXING) hinzu Nein für das App-Target.

No such module 'Capacitor'. Du hast App.xcodeproj. Öffne App.xcworkspace, oder führe bunx cap open ios.

pod: command not found in der CI aus. Installiere CocoaPods im Job oder nutze Bundler mit einem gecachten vendor/bundle. Ohne CocoaPods loggt CLI „Skipping pod install because CocoaPods is not installed“ und der Build schlägt später fehl.

Weitere iOS-Build-Fehler findest du im Capacitor iOS-Troubleshooting-Guide.

Das CocoaPods Trunk Read-only-Datum

Die CocoaPods-Maintainer haben angekündigt, dass trunk, das zentrale Spec-Repository, nach einer Testphase Anfang November 2026 am 2. Dezember 2026 schreibgeschützt wird. Das bedeutet für eine Capacitor App:

• Bestehende Builds funktionieren weiterhin. Alle veröffentlichten Podspecs bleiben verfügbar.
• Keine neuen Versionen mehr über trunk. SDKs, die du über trunk beziehst (Firebase, Google ML Kit, Vendor-SDKs), erhalten dort keine Updates mehr. Security-Fixes und neuer iOS SDK Support werden nur noch über SPM oder andere Kanäle bereitgestellt.
• Capacitor Plugins selbst sind nicht direkt betroffen. Sie werden über npm installiert und über :path im Podfile referenziert. Das gilt auch für deren transitive Pod-Dependencies.

Nutze CocoaPods als Brücke. Liste die Dependencies auf, die dich daran binden, und wechsle, sobald diese SPM-Support bieten.

Der Umstieg von CocoaPods

Wenn du bereit bist:

bunx cap spm-migration-assistant

Es läuft pod deintegrate, entfernt den Podfile, Podfile.lock und App.xcworkspace, erstellt CapApp-SPM, und schreibt eine debug.xcconfig. Danach fügst du CapApp-SPM als lokales Package in Xcode hinzu und setzt debug.xcconfig als Debug-Konfigurationsdatei. Die vollständige Anleitung findest du in wie du deine Capacitor App auf SPM migrierst, und die Vor- und Nachteile werden in SPM vs. CocoaPods für Capacitor behandelt.

Plugin-Autoren, die SPM-Support hinzufügen müssen, sollten lesen: Migration eines Capacitor Plugins zu SPM.

Wenn das Verwalten von Ruby-, CocoaPods- und Xcode-Versionen auf Build-Maschinen der mühsame Teil ist, Capgo Build baut CocoaPods- und SPM-Projekte in der Cloud mit aktuellem Xcode.