So migrierst du eine Capacitor-App zum Swift Package Manager

Capacitor 8 erstellt neue iOS-Projekte standardmäßig mit Swift Package Manager (SPM). Bestehende Apps, die noch CocoaPods nutzen, können ebenfalls migrieren, aber der sicherste Weg hängt davon ab, wie stark deine App nativ für iOS angepasst wurde.

Dieser Guide zeigt dir, was sich ändert, was du sichern musst und die zwei praktischen Migrationswege: die Nutzung des Capacitor Migration Assistants oder das Re-Scaffolding des iOS-Projekts mit SPM.

Warum jetzt migrieren?

CocoaPods bewegt sich in Richtung eines Read-only-Trunks. Der aktuelle Plan sieht vor, dass der CocoaPods-Trunk ab dem... 2. Dezember 2026. Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Dependency-Updates, die auf trunk basieren, werden nach der Umstellung dort nicht mehr veröffentlicht.

SPM ist auch die Richtung, in die sich Capacitor bewegt. Capacitor unterstützt die Wahl zwischen CocoaPods oder SPM bereits seit Capacitor 6, und Capacitor 8 erstellt iOS SPM-Projekte nun als Standard-Template.

Was sich in einem Capacitor SPM-Projekt ändert

Die Migration von CocoaPods zu SPM ersetzt die iOS-Dependency-Schicht. Die Web-App, das Android-Projekt und die meisten Capacitor Workflow-Commands bleiben unverändert.

CapApp-SPM ersetzt das Podfile

In einer CocoaPods-App laufen die iOS-Dependencies über ios/App/Podfile, Podfile.lock, Pods/, und die generierte .xcworkspace.

In einer SPM-App erstellt Capacitor ein lokales Package namens CapApp-SPM. Dieses Package wird zur zentralen Stelle, an der Capacitor deine nativen iOS-Plugin-Dependencies referenziert. Die Capacitor CLI Updates CapApp-SPM werden beim Plugin-Sync aktualisiert – behandle es daher als generierten Output und ändere es nicht von Hand.

debug.xcconfig ersetzt die Pods-Konfiguration

Der Migrations-Assistent erstellt außerdem eine generierte debug.xcconfig. Diese Datei enthält Build-Einstellungen, die CocoaPods früher über seine generierten xcconfig-Dateien bereitgestellt hat.

Nach der Migration müssen Sie eventuell debug.xcconfig in der Xcode-Projektkonfiguration hinzufügen, falls der Assistent Sie dazu auffordert.

Jedes Plugin muss SPM unterstützen

Sie können CocoaPods und SPM nicht im selben Capacitor iOS-Projekt mischen. Prüfen Sie vor der Migration jedes Capacitor und Cordova-Plugin in package.json.

Falls ein Plugin SPM noch nicht unterstützt, aktualisieren, ersetzen oder migrieren Sie das Plugin zuerst. Einfache Swift-Plugins lassen sich oft mit Ionics capacitor-plugin-converterkonvertieren, aber Plugins mit komplexeren Objective-C- und Swift-Strukturen erfordern eventuell manuelle Anpassungen.

Was zuerst gesichert werden sollte

Starten Sie mit einem sauberen Git-Branch und committen Sie Ihren aktuellen Stand, bevor Sie das iOS-Projekt anfassen. Listen Sie dann die nativen Dateien auf, von denen Ihre App abhängt.

Häufig zu sichernde Dateien aus ios/App/ umfassen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, falls deine App eine hat
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, falls du Firebase nutzt
Individuell .xcconfig Dateien
Signing-Einstellungen, Bundle Identifier, Team ID und Einstellungen für Provisioning-Profile

Behalte außerdem alle nativen Swift-, Objective-C-, Framework-, Extension- oder SDK-Dateien, die du außerhalb des Standard-Templates von Capacitor hinzugefügt hast.

Option 1: Nutze den Capacitor Migrations-Assistenten

Wähle diesen Weg, wenn dein iOS-Projekt eigene native Änderungen enthält, die du nicht verlieren möchtest.

Starte den Assistenten im Root-Verzeichnis deines Capacitor-Projekts:

bunx cap spm-migration-assistant

Der Assistent entfernt die CocoaPods-Infrastruktur, erstellt das lokale CapApp-SPM Package, generiert Package-Referenzen aus deinen installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien.

Sobald er fertig ist, öffne das Projekt:

bunx cap open ios

Folge dann den manuellen Xcode-Schritten des Assistenten. In den meisten Projekten bedeutet das:

Füge CapApp-SPM als lokale Package-Dependency.
Füge das generierte debug.xcconfig zur App-Konfiguration hinzu.
Behebe alle Warnungen zu Plugins, die nicht in SPM konvertiert werden konnten.
Baue die App einmal in Xcode, bevor du die CI aktualisierst.

Nachdem das Xcode-Projekt gebaut wurde, erneut synchronisieren:

bunx cap sync ios

Option 2: iOS-Projekt mit SPM neu aufsetzen

Wähle diesen Weg, wenn dein ios/ Verzeichnis nah am Standard-Capacitor Template liegt und du eigene Dateien danach sicher wiederherstellen kannst.

Stelle zuerst sicher, dass die im Backup-Abschnitt gelisteten Dateien committed oder sicher kopiert wurden. Entferne dann das iOS-Projekt und erstelle es mit SPM neu:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Stelle die benötigten nativen Dateien deiner App wieder her und öffne dann das Projekt:

bunx cap open ios

Dieser Weg ist oft sauberer als eine In-Place-Migration, da du ein frisches Capacitor 8 iOS-Template erhältst. Der Nachteil ist, dass du Signing, Entitlements, Firebase-Dateien, Änderungen am nativen Quellcode und alle benutzerdefinierten Xcode-Einstellungen sorgfältig neu anwenden musst.

Neue Capacitor-Apps

Bei einer neuen App nutzt Capacitor 8 standardmäßig SPM beim Hinzufügen von iOS:

bunx cap add ios

Falls du es explizit angeben möchtest, kannst du weiterhin die Package-Manager-Option übergeben:

bunx cap add ios --packagemanager SPM

CI nach der Migration aktualisieren

Sobald die App lokal baut, aktualisiere die CI/CD, damit sie nicht mehr von CocoaPods ausgeht.

Entferne Schritte, die Folgendes ausführen:

pod install

Entferne auch die Caches für:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods-Specs-Repositories, falls dein Workflow diese nur für diese App gecacht hat

Behalte deine regulären Web-Build- und Capacitor-Sync-Schritte bei. Ein typischer iOS-Job sollte JavaScript-Abhängigkeiten installieren, die Web-Assets bauen, Capacitor synchronisieren und dann mit Xcode bauen:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Migration-Checkliste

Vor der Migration:

Erstelle einen neuen Git-Branch.
Committe die aktuell funktionierende App.
Prüfe, ob alle installierten Plugins SPM unterstützen.
Halte eigene iOS-Dateien und Signing-Einstellungen fest.
Stelle sicher, dass der Build vor der Migration läuft.

Während der Migration:

Ausführen bunx cap spm-migration-assistant oder neu scaffolden ios/.
Füge CapApp-SPM falls erforderlich in Xcode.
Füge debug.xcconfig falls erforderlich in Xcode.
App-spezifische native Dateien wiederherstellen.
Ausführen bunx cap sync ios.

Nach der Migration:

App in Xcode bauen und ausführen.
Übrig gebliebene CocoaPods-Dateien entfernen.
Entfernen pod install aus der CI.
Prüfen, ob das Release-Signing noch funktioniert.
App vor dem Release auf mindestens einem Simulator und einem echten Gerät testen.

Fehlerbehebung

Falls Xcode Packages nicht auflösen kann, Package-Caches in Xcode zurücksetzen und ausführen bunx cap sync ios erneut aus.

Falls die Migration wegen eines Plugins fehlschlägt, prüfe, ob es eine neuere Version mit SPM-Support gibt. Bei eigenen Plugins migriere zuerst das Plugin-Package und kehre dann zur App-Migration zurück.

Wenn der lokale Build funktioniert, aber die CI fehlschlägt, prüfe auf veraltete CocoaPods-Annahmen. Häufige Ursachen sind ein erzwungener .xcworkspace Build-Pfad, ein veralteter pod install Befehl oder Caching Pods/ aus vorherigen Builds.

Fazit

Die Migration einer Capacitor App auf Swift Package Manager besteht primär darin, die iOS-Dependency-Struktur zu ersetzen. CapApp-SPM übernimmt die Dependency-Referenzen, debug.xcconfig ersetzt die generierte CocoaPods-Build-Konfiguration, und die CI benötigt diese nicht mehr. pod install.

Bei angepassten iOS-Projekten beginne mit bunx cap spm-migration-assistant. Bei Projekten, die nah am Standard-Template liegen, ist ein sauberes SPM-Re-Scaffolding oft schneller und einfacher nachvollziehbar.

Ressourcen

Weiterlesen: So migrierst du eine Capacitor App zum Swift Package Manager

Wenn du es nutzt So migrierst du eine Capacitor-App zum Swift Package Manager um Migration und Enterprise-Betrieb zu planen, verbinde es mit Capgo Enterprise für den Produkt-Workflow in Capgo Enterprise, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen, Capgo Alternativen für den Produkt-Workflow in Capgo Alternativen, Capgo Beratung für den Produkt-Workflow in Capgo Consulting und Capgo Premium-Support für den Produkt-Workflow in Capgo Premium Support.