Mit CocoaPods arbeiten: Capacitor 8 (und wann nicht)

Um CocoaPods mit Capacitor 8 zu verwenden, erstellen Sie das iOS-Plattform mit bunx cap add ios --packagemanager CocoaPodsinstallieren Sie CocoaPods (Homebrew oder ein Gemfile mit Bundler) und lassen Sie bunx cap sync ios verwalten Sie das Podfile und führen Sie pod install. Capacitor 8 unterstützt CocoaPods noch vollständig. Die Standard-Einstellung für neue Projekte wurde jedoch auf Swift Package Manager geändert.

CocoaPods ist nicht mehr die langfristige Richtung, und sein Hauptzweig wird ab dem 2. Dezember 2026 nur noch lesend zugänglich sein. Die Frage ist also, wann es noch die richtige Wahl ist, wie man es weiterhin nutzen kann und wie man es sauber verlässt. Diese Anleitung behandelt alle drei Aspekte.

Wenn CocoaPods noch die richtige Wahl ist

Bleiben Sie bei CocoaPods, oder wählen Sie CocoaPods, wenn eines dieser ist wahr:

• Ein Plugin, das Sie benötigen, ist nicht verfügbar. Package.swift. In einem SPM-Projekt warnt CLI 'Einige installierte Capacitor-Plugins sind nicht mit SPM kompatibel' und lässt das Plugin aus, sodass es bei der Ausführung mit 'Plugin ist nicht implementiert' fehlschlägt.
• Ein Vendor SDK wird nur als Pod verteilt. Einige Analyse-, Zahlungs- und Identitäts-SDKs liefern nur CocoaPods oder liefern ein xcframework, das Sie selbst umwickeln müssen.
• Ein Cordova-Plugin hängt von Pods ab. Capacitor erzeugt eine Swift-Paket für Cordova-Plugins in SPM-Projekten, aber komplexe mit <podspec> Sie hängen von podspec-Subspezifikationen ab.
• Sie setzen sich auf Podspec-Subspezifikationen ab. um SDK-Varianten auszuwählen. SPM verfügt nun über Paketmerkmale, und Capacitor unterstützt sie seit CLI 8.3 experimentell (siehe SPM-Paketmerkmale in Capacitor), aber das Plugin muss zunächst Merkmale definieren.
• Ein großes, angepasstes Xcode-Projekt wobei eine Migration in diesem Release-Zyklus nicht wert ist.

Paketidentitätskollisionen waren früher ein weiterer Grund. Seit CLI 8.4 können Sie sie in SPM umgehen mit experimental.ios.spm.packageOptions (symlink oder moduleAliasesin Ihrem Capacitor-Konfiguration.

Wenn keine dieser Optionen zutreffen, verwenden Sie SPM. Es benötigt keine Ruby-Toolchain, keinen Podfile und keine .xcworkspace.

CocoaPods vs SPM in Capacitor 8

CocoaPods installieren

Wählen Sie eine Methode und verwenden Sie sie überall, einschließlich CI.

Homebrew (am einfachsten für einen Entwickler):

brew install cocoapods
pod --version

Bundler (fixiert die Version für die gesamte Team, empfohlen für CI). Erstellen Sie ein Gemfile in der Projektwurzel oder in ios/App:

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

bundle install

Wenn der Capacitor CLI eine Gemfile Wenn es CocoaPods erwähnt, läuft es bundle exec pod install anstatt pod install. If pod lebt irgendwo ungewöhnlich, setzt CAPACITOR_COCOAPODS_PATH Erstellen Sie ein __CAPGO_KEEP_0__ 8-App mit CocoaPods

Erstellen Sie 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 opens App.xcworkspace. Bauen Sie immer aus dem Workspace. Öffnen App.xcodeproj Dies ist die Podfile __CAPGO_KEEP_0__ 8 generiert: No such module 'Capacitor'.

Was Sie berühren und was nicht:

Dies ist die Podfile 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 Sie berühren und was nicht:

• def capacitor_pods ... end gehört zum CLI. Bei jedem Synchronisierungsprozess ersetzt es den gesamten Block mit einem. pod Jedes, was du hinzufügst, wird verloren. node_modulesFüge deine eigenen Pods unter
• Fügen Sie Ihre eigenen Pods unter 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 Beispiel mit einem zusätzlichen Pod und einem Build-Einstellung-Fix:
• platform :ios Muss mindestens 15.0 für Capacitor 8 sein.

Beispiel mit einem zusätzlichen Pod und einem Build-Einstellung-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

Der Loop deaktiviert code-Signierung für Ressourcenbundle-Ziele. Es behebt Signing for "X" requires a development team fügen Sie es nur hinzu, wenn Sie diesen Fehler erhalten.

Tag-to-tag Befehle

# 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 läuft auch xcodebuild clean auf dem Projekt nach pod install, damit du keine manuelle Reinigung nach dem Hinzufügen von Plugins benötigst.

Commit Podfile und Podfile.lock, mach keine Commit. ios/App/Pods/, es wird durch pod install.

Wechseln Sie eine bestehende App von SPM zu CocoaPods

Es gibt keine Umkehrungsmigration-Befehl. Mach es manuell:

1. Commit, kopiere dann ios/ etwas sicher auf.
2. Löschen ios/.
3. Ausführen bunx cap add ios --packagemanager CocoaPods.
4. Reapplizieren Sie native Änderungen: Info.plist Entitäten, Schlüssel, Fähigkeiten, Signierungsteam, Bundle-Bezeichner, App-Icons und Splash-Assets, URL-Schemas, Erweiterungen (Widgets, Benachrichtigungsdienst) und beliebige benutzerdefinierte Swift-Code. AppDelegate.
5. bunx cap sync ios und bauen.

Vergleich der alten und neuen ios/App/App Ordner ist der schnellste Weg, was du verpasst hast.

Behebung häufiger CocoaPods-Fehler

CocoaPods could not find compatible versions for pod "X". Entweder ist Ihr lokales Spezifikations-Repository veraltet oder zwei Pods erfordern inkompatible Versionen. Führen Sie pod install --repo-update in ios/AppWenn es immer noch nicht funktioniert, lesen Sie die Abhängigkeitskette im Fehler, finden Sie das Plugin mit der strengen Pin-Einstellung, upgraden Sie es oder Patching seine Podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Die Pods Ordner passt nicht zum Lock-File, meist nachdem man zwischen Branches gewechselt hat. Run bunx cap sync ios.

[!] Unable to find a specification for 'X'. Die Spezifikations-Repo-Cache ist veraltet oder der Pod-Name ist falsch. Führen Sie pod repo update.

Unable to find compatibility version string for object version '70' (or 77Dein Xcode-Projekt verwendet eine neueren Format als CocoaPods/xcodeproj-Gem versteht. Aktualisiere CocoaPods auf die neueste Version. Wenn dies nicht möglich ist, sichere zunächst deine Projekte. project.pbxproj setzen objectVersion zu einem Wert, den CocoaPods unterstützt.

Sandbox: rsync(...) deny(1) file-write-create. Xcode's Benutzerskript-Sandboxing blockiert das CocoaPods-Embed-Skript. Build Einstellungen, set Einstellungen für das Build-Prozess (ENABLE_USER_SCRIPT_SANDBOXING, setze No kein App-Target

No such module 'Capacitor'. Sie haben App.xcodeproj. Öffnen App.xcworkspace, oder ausführen bunx cap open ios.

pod: command not found im CI. CocoaPods in der Aufgabe installieren, oder Bundler mit einem gecacherten vendor/bundle. Ohne es, werden die CLI-Protokolle “Pod-Installatoren überspringen, da CocoaPods nicht installiert ist” und der Build scheitert später.

Mehr Fehler bei der iOS-Buildung werden im iOS-Fehlersuchguide von Capacitor behandelt.

Der CocoaPods-Trunk wird am

Die CocoaPods-Maintainer haben bekannt gegeben, dass der Trunk, der zentrale Spezifikations-Repository, ab dem 2. Dezember 2026 nach einer Testphase im November 2026 nur noch lesbar ist. Was das für eine Capacitor-App bedeutet:

• Bestehende Builds funktionieren weiterhin. Jedes veröffentlichte Podspec bleibt verfügbar.
• Keine neuen Versionen über den Trunk. SDKs, die Sie aus dem Trunk (Firebase, Google ML Kit, Anbieter-SDKs) ziehen, erhalten dort keine Updates mehr. Sicherheitspatches und neue iOS SDK-Unterstützung werden nur über SPM oder andere Kanäle bereitgestellt.
• Capacitor-Plugins selbst werden nicht direkt betroffen. Sie werden von npm installiert und durch :path referenziert in der Podfile. Ihre transitive Pod-Abhängigkeiten sind.

Treiben Sie CocoaPods als Brücke auf. Listen Sie an, welche Abhängigkeit Sie auf CocoaPods festhält, und besuchen Sie sie, wenn diese Abhängigkeit SPM-Unterstützung hinzufügt.

Abstieg von CocoaPods

Wenn Sie bereit sind:

bunx cap spm-migration-assistant

Es läuft pod deintegrate, entfernt die Podfile, Podfile.lock und App.xcworkspace, erstellt CapApp-SPM, und schreibt ein debug.xcconfigSie fügen dann CapApp-SPM als lokalen Paket in Xcode hinzu und setzen debug.xcconfig als Debug-Konfigurationsdatei. Der vollständige Leitfaden finden Sie in wie Sie Ihre Capacitor-App auf SPM migrieren, und die Vor- und Nachteile werden in SPM gegenüber CocoaPods für Capacitor.

Plugin-Autoren, die eine SPM-Unterstützung hinzufügen müssen, sollten lesen eine Capacitor-Plugin auf SPM migrieren.

Wenn die Verwaltung von Ruby, CocoaPods und Xcode-Versionen auf Build-Maschinen der schmerzhafte Teil ist, Capgo Build CocoaPods und SPM-Projekte in der Cloud auf aktuellen Xcode bauen