So migrierst du deine Capacitor App zum Swift Package Manager

Swift Package Manager ist der Standardweg für Capacitor-iOS-Projekte. Wenn deine App noch CocoaPods nutzt, kannst du die App selbst auf SPM migrieren, ohne dein JavaScript-code, dein Android-Projekt oder deinen Release-Workflow von Grund auf neu aufzubauen.

Dieser Guide richtet sich an App-Teams. Er erklärt, wie du eine Capacitor-iOS-App von CocoaPods auf SPM migrierst, was der Migration Assistant ändert, was du in Xcode noch prüfen musst und wie du die CI nach dem App-Build aufräumst.

Was sich in der App ändert

Eine CocoaPods-basierte Capacitor-App hängt von Dateien wie diesen ab:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Eine Capacitor App auf SPM-Basis verlagert das iOS-Dependency-Management in den Swift Package Manager. Während der Migration erstellt Capacitor ein lokales Package namens CapApp-SPM und nutzt dieses, um das App-Target mit Capacitor und den installierten nativen Dependencies zu verbinden.

Der Web-Build funktioniert weiterhin wie gewohnt. Du führst den Web-Build aus, syncst Capacitor, öffnest Xcode und archivierst die App. Der Hauptunterschied ist, dass CocoaPods nicht mehr den iOS-Dependency-Graph verwaltet.

Bevor du migrierst

Starte von einem sauberen Branch und stelle sicher, dass die aktuelle App buildet, bevor du den Dependency Manager änderst:

git status
npm run build
npx cap sync ios

Committe danach den funktionierenden Zustand. Da die Migration generierte iOS-Projektdateien verändert, ist ein sauberer Rollback-Punkt wichtig.

Überprüfe als Nächstes, welche Anpassungen deine App unter ios/App/. Common files and settings to preserve include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, falls vorhanden
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, falls du Firebase nutzt
custom .xcconfig Dateien
Signing-Einstellungen, Bundle Identifier, Team ID und Provisioning-Profile
App Extensions, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

Prüfe auch deine installierten Capacitor und Cordova-Abhängigkeiten. Eine SPM-Migration auf App-Ebene kann durch eine native Abhängigkeit blockiert werden, die keinen SPM-kompatiblen Pfad hat. Aktualisiere diese Pakete nach Möglichkeit vor der Migration.

Nutze den Migration Assistant

Für die meisten bestehenden Apps starte mit dem offiziellen Capacitor Migration Assistant:

npx cap spm-migration-assistant

Führe ihn im Root deines Capacitor-Projekts aus. Der Assistant entfernt die CocoaPods-Integration, erstellt das lokale CapApp-SPM Package, generiert Package-Referenzen für installierte native Abhängigkeiten und fügt die generierte Konfiguration hinzu, die das iOS-Projekt braucht.

Nach Abschluss öffne das iOS-Projekt:

npx cap open ios

Lies die Ausgabe des Assistants, bevor du das Terminal schließt. Wenn er dich bittet, manuelle Xcode-Schritte auszuführen, erledige diese vor dem nächsten Sync.

Xcode-Schritte abschließen

Prüfe in Xcode die App-Projekt- und Target-Konfiguration:

Bestätigen CapApp-SPM wird als lokale Package-Dependency hinzugefügt.
Stelle sicher, dass das App-Target die generierten Package-Produkte verlinkt.
Füge das generierte debug.xcconfig der Projektkonfiguration hinzu, falls der Assistent danach fragt.
Behebe etwaige Package-Warnungen in Xcode.
Baue die App einmalig über Xcode.

Falls Xcode Packages nicht auflösen kann, nutze File > Packages > Reset Package Caches, und löse die Packages erneut auf.

Sync und Build erneut durchführen

Nachdem Xcode konfiguriert ist, kehre zum Terminal zurück und sync Capacitor:

npx cap sync ios

Baue dann erneut über Xcode. Betrachte die Migration erst als abgeschlossen, wenn ein Clean Build in Xcode funktioniert, da Release Signing, Entitlements, App Extensions und die Package-Resolution dort validiert werden.

Falls die App Push-Benachrichtigungen, Associated Domains, Background Modes, App Groups, Firebase oder eine native SDK Konfiguration nutzt, teste diese Flows nach einem erfolgreichen Build auf einem Simulator oder Gerät.

Alternative: iOS mit SPM neu erstellen

Falls dein ios/ Wenn der Ordner nah am Standard-Capacitor-Template liegt, kann es schneller sein, ihn mit SPM neu zu erstellen, statt eine Migration vor Ort durchzuführen.

Nutze diesen Weg nur, nachdem du alle benötigten nativen Dateien und Signing-Einstellungen committet oder gesichert hast:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Stelle danach deine app-spezifischen nativen Dateien und Einstellungen wieder her. Dieser Weg liefert ein sauberes SPM-Projekt, aber man verliert leichter eigene Xcode-Änderungen, wenn man sie vorher nicht dokumentiert hat.

Für neue Capacitor Apps erstellt Capacitor 8 iOS-Projekte standardmäßig mit SPM:

npx cap add ios

Du kannst es auch explizit angeben:

npx cap add ios --packagemanager SPM

CocoaPods-Überreste bereinigen

Nachdem die SPM-App gebaut wurde, entferne verbleibende CocoaPods-Abhängigkeiten aus lokalen Skripten und der CI.

Entferne Schritte wie:

pod install

Entferne auch Caches, die nur für CocoaPods existierten:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods-Specs-Repositories
CI-Cache-Keys basierend auf dem Podfile

Ein einfacher CI-Flow nach der Migration sollte JavaScript-Abhängigkeiten installieren, die Web-App bauen, Capacitor synchronisieren und mit Xcode bauen:

npm ci
npm run build
npx cap sync ios

Falls deine CI noch baut App.xcworkspace, aktualisiere sie auf den Projekt- oder Workspace-Pfad, der nach der Migration existiert. Behalte keine veralteten CocoaPods-Pfade bei, nur weil der alte Job sie verwendet hat.

Fehlerbehebung

Der Assistant warnt vor einer inkompatiblen Dependency

Aktualisiere zuerst die Dependency und starte den Assistant erneut. Falls keine SPM-kompatible Version existiert, bleibe bei CocoaPods, bis du die Dependency ersetzt oder der Maintainer SPM-Support hinzufügt.

Xcode kann Packages nicht auflösen

Setze die Package-Caches in Xcode zurück, prüfe, ob CapApp-SPM als lokales Package vorhanden ist, und führe npx cap sync ios erneut aus.

App baut lokal, aber CI schlägt fehl

Prüfe auf veraltete CocoaPods-Annahmen: pod install, Pods/ Caches, Podfile.lock Cache-Keys oder Build-Commands, die auf ein gelöschtes Ziel verweisen .xcworkspace.

Signing oder Entitlements haben sich geändert

Vergleiche das migrierte Xcode-Target mit dem Projekt vor der Migration. Stelle Bundle Identifier, Team, Provisioning Profile, Entitlements-Datei, Capabilities und Extension-Settings wieder her.

Migration-Checkliste

Vor der Migration:

Erstelle einen Branch.
Bestätige, dass die aktuelle iOS-App baut.
Commit den funktionierenden Zustand.
Inventur der benutzerdefinierten Native-Files und Signing-Settings.
Native Dependencies aktualisieren, die bereits neuere SPM-kompatible Releases haben.

Während der Migration:

Ausführen npx cap spm-migration-assistant.
Projekt öffnen mit npx cap open ios.
Füge CapApp-SPM falls erforderlich in Xcode.
Füge debug.xcconfig falls erforderlich in Xcode.
Package-Warnungen beheben.
Ausführen npx cap sync ios.

Nach der Migration:

Die App in Xcode builden.
Native Funktionen auf einem Simulator oder Gerät testen.
CocoaPods-Befehle aus der CI entfernen.
Nur von CocoaPods genutzte Caches entfernen.
Archive und Release-Signing überprüfen.

Nutze Capgo Skills für die Migration

Wenn du KI-Agenten für die Migration nutzt, starte mit Capgo Skills statt mit einem leeren Prompt. Die nützlichsten Skills für diese Aufgabe sind:

capacitor-best-practices die App-Struktur vor Änderungen zu prüfen, ios/.
cocoapods-to-spm die SPM-Migration und die Xcode-Folgeschritte zu planen,
capacitor-ci-cd CocoaPods-Annahmen aus Build-Pipelines zu entfernen.
debugging-capacitor und ios-android-logs um gerätespezifische Probleme nach der Migration zu untersuchen.

Nutze sie, bevor du das iOS-Projekt änderst, damit der Agent native Dateien, CI und Dependency-Kompatibilität prüft, statt nur den Migrationsbefehl auszuführen.

Fazit

Die Migration einer Capacitor App zu Swift Package Manager ist größtenteils eine Änderung am iOS-Dependency-Management. Der sicherste Weg ist, von einem sauberen Branch zu starten, den Befehl auszuführen und npx cap spm-migration-assistantdie manuellen Xcode-Schritte abzuschließen, erneut zu synchronisieren und CocoaPods erst aus der CI zu entfernen, wenn die App baut.

Falls dein iOS-Projekt stark angepasst ist, migriere in-place. Wenn es nah am Standard-Capacitor-Template ist, kann ein Neuaufsetzen ios/ mit npx cap add ios --packagemanager SPM sauberer sein.