Wie migriert man eine Capacitor-App zum Swift Package Manager?

Capacitor 8 erstellt neue iOS-Projekte mit Swift Package Manager (SPM) standardmäßig. Bestehende Apps, die CocoaPods noch verwenden, können migriert werden, aber der sicherste Weg hängt von der Menge an nativen iOS-Anpassungen ab, die Ihre App hat.

Diese Anleitung führt durch die Änderungen, die Sicherung von Daten und die beiden praktischen Migrationen: die Verwendung des Capacitor-Migrationsassistenten oder die Neukonstruktion des iOS-Projekts mit SPM.

Warum jetzt migrieren?

CocoaPods wird sich auf eine lesende Truhe ausrichten. Derzeitiger Plan ist, dass die CocoaPods-Truhe ab dem 2. Dezember 2026 keine neuen Podspecs mehr akzeptieren wird. 2. Dezember 2026Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsaktualisierungen, die auf der Truhe basieren, werden dort nicht mehr veröffentlicht, nachdem der Wechsel erfolgt ist.

SPM ist auch die Richtung, in die Capacitor sich bewegt. Capacitor unterstützt seit Capacitor 6 die Auswahl zwischen CocoaPods und SPM und Capacitor 8 erstellt nun iOS-SPM-Projekte als Standardtemplate.

Welche Änderungen gibt es in einem Capacitor-SPM-Projekt?

Die Umstellung von CocoaPods auf SPM ersetzt die iOS-Abhängigkeitslayer. Die Web-App, das Android-Projekt und die meisten Capacitor-Workflow-Befehle bleiben unverändert.

CapApp-SPM ersetzt die Podfile.

In einer CocoaPods-Anwendung werden die iOS-Abhängigkeiten über ios/App/Podfile, Podfile.lock, Pods/, und die generierte .xcworkspace.

In einer SPM-Anwendung erstellt Capacitor eine lokale Paketdatei mit dem Namen CapApp-SPM. Diese Paketdatei wird zum zentralen Ort, an dem Capacitor Ihre native iOS-Plugin-Abhängigkeiten referenziert. Die Capacitor CLI-Aktualisierungen CapApp-SPM werden automatisch aktualisiert, wenn Sie Plugins synchronisieren, daher sollten Sie es als generiertes Ausgabe behandeln und es nicht manuell bearbeiten.

debug.xcconfig ersetzt Pods-Konfiguration

Der Migration-Assistent erstellt auch einen generierten debug.xcconfigDieses File trägt Build-Einstellungen, die CocoaPods früher durch seine generierten xcconfig-Files bereitstellte.

Nach der Migration müssen Sie möglicherweise debug.xcconfig zum Xcode-Projekt-Konfiguration hinzufügen, wenn der Assistent Ihnen dazu auffordert.

Jeder Plugin muss SPM unterstützen

Sie können CocoaPods und SPM nicht in demselben Capacitor iOS-Projekt mischen. Bevor Sie migrieren, überprüfen Sie alle Capacitor und Cordova-Plugins in package.json.

Wenn ein Plugin SPM noch nicht unterstützt, aktualisieren Sie es, ersetzen Sie es oder migrieren Sie das Plugin zuerst. Simple Swift-Plugins können oft mit Ionic’s capacitor-plugin-converterkonvertiert werden, aber Plugins mit komplexeren Objective-C- und Swift-Anordnungen benötigen möglicherweise manuelle Arbeit.

Was zuerst sichern

Beginnen Sie mit einer sauberen Git-Branch und committen Sie Ihren aktuellen Zustand, bevor Sie das iOS-Projekt anfassen. Dann listen Sie die native Files auf, auf die Ihre App angewiesen ist.

Gemeinsame Dateien, die Sie vor der Migration speichern sollten ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, wenn Ihr App eine hat
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, wenn Sie Firebase verwenden
Benutzerdefiniert .xcconfig Dateien
Signierungs-Einstellungen, Bundle-Identifier, Team-ID und Bereitstellungsprofil-Einstellungen

Behalten Sie auch alle native Swift, Objective-C, Framework, Erweiterung oder SDK-Dateien, die Sie außerhalb des Standard-Capacitor-Templates hinzugefügt haben.

Option 1: Verwenden Sie den Capacitor-Migration-Assistenten

Verwenden Sie diesen Pfad, wenn Ihre iOS-Projekt benutzerdefinierte native Änderungen enthält, die Sie nicht verlieren möchten.

Führen Sie den Assistenten vom Root Ihres Capacitor-Projekts aus:

bunx cap spm-migration-assistant

Der Assistent entfernt die CocoaPods-Infrastruktur, erstellt die lokale Paketdatei, generiert Paketverweise aus Ihren installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien. CapApp-SPM The assistant removes the CocoaPods infrastructure, creates the local package, generates package references from your installed plugins, and creates the generated SPM configuration files.

Wenn es fertig ist, öffnen Sie das Projekt:

bunx cap open ios

Folgen Sie dann den manuellen Xcode-Schritten, die vom Assistenten ausgegeben werden. In den meisten Projekten bedeutet dies:

Hinzufügen CapApp-SPM als lokale Paketabhaengigkeit.
Fügen Sie die generierte debug.xcconfig der Anwendungskonfiguration hinzu.
Beheben Sie Warnungen über Plugins, die nicht in SPM umgewandelt werden konnten.
Bauen Sie die App aus Xcode einmal vor der Aktualisierung von CI.

Nachdem die Xcode-Projekt erstellt wurde, synchronisieren Sie sich noch einmal:

bunx cap sync ios

Option 2: Erstellen Sie das iOS-Projekt mit SPM neu

Verwenden Sie diesen Pfad, wenn Ihr ios/ Verzeichnis sich in der Nähe der Standardvorlage Capacitor befindet und Sie Ihre benutzerdefinierten Dateien sicher wiederherstellen können.

Zuerst stellen Sie sicher, dass die in der Sicherungskopie aufgeführten Dateien abgelegt oder kopiert wurden. Dann entfernen und erneut erstellen Sie das iOS-Projekt mit SPM:

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

Rufen Sie die native Dateien auf, die Ihre App benötigt, und öffnen Sie dann das Projekt:

bunx cap open ios

Dieser Pfad ist oft sauberer als eine in-Place-Migration, da er Ihnen ein frisches Capacitor 8 iOS-Vorlage gibt. Der Handelnde ist jedoch, dass Sie die Signierung, die Berechtigungen, die Firebase-Dateien, die native Quellcodeänderungen und jede benutzerdefinierte Xcode-Einstellung sorgfältig wieder anwenden müssen.

Neue Capacitor Apps

Für eine neue App verwendet Capacitor 8 SPM standardmäßig, wenn Sie iOS hinzufügen:

bunx cap add ios

Wenn Sie explizit sein müssen, können Sie den Paket-Manager-Option immer noch übergeben:

bunx cap add ios --packagemanager SPM

Update CI nach der Migration

Einmal das App lokal gebaut hat, aktualisieren Sie CI/CD, damit es nicht mehr davon ausgeht, dass CocoaPods verwendet wird.

Entfernen Sie Schritte, die ausführen:

pod install

Entfernen Sie auch die Caches für:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods-Spezifikations-Repositories, wenn Ihr Workflow sie nur für diese App gecacht hat

Halten Sie Ihre reguläre Web-Ausführung und Capacitor-Synchronisierungsschritte bei. Ein typischer iOS-Auftrag sollte die JavaScript-Abhängigkeiten installieren, die Web-Ressourcen bauen, Capacitor synchronisieren und dann mit Xcode bauen:

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

Migrationscheckliste

Bevor die Migration:

Erstellen Sie einen neuen Git-Zweig.
Kommentieren Sie die aktuelle Arbeitsanwendung.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Sicherstellen Sie, dass benutzerdefinierte iOS-Dateien und Signierungseinstellungen aufgezeichnet sind.
Bestätigen Sie, dass die Anwendung vor der Migration erfolgreich kompiliert wird.

Während der Migration:

Ausführen bunx cap spm-migration-assistant oder erneut aufbauen ios/.
Hinzufügen CapApp-SPM in Xcode erforderlich.
Hinzufügen debug.xcconfig in Xcode falls erforderlich.
App-spezifische native Dateien wiederherstellen.
Ausführen bunx cap sync ios.

Nach der Migration:

Die App in Xcode erstellen und ausführen.
Überbleibende CocoaPods-Dateien entfernen.
Entfernen pod install aus der CI.
Überprüfen, ob die Release-Zertifizierung noch funktioniert.
Die App auf mindestens einem Simulator und einem realen Gerät ausführen, bevor Sie sie verschicken.

Fehlersuche

If Xcode kann die Pakete nicht auflösen, löschen Sie die Paket-Caches von Xcode und führen Sie den Befehl erneut aus. bunx cap sync ios Wiederholen Sie den Befehl.

Wenn die Migration aufgrund eines Plugins fehlschlägt, überprüfen Sie, ob das Plugin eine neue Version mit SPM-Unterstützung hat. Für Plugins, die Sie selbst verwalten, migrieren Sie das Plugin-Paket zuerst und kehren dann zur App-Migration zurück.

Wenn das App-Programm lokal erfolgreich kompiliert, aber die CI-Funktion fehlschlägt, überprüfen Sie alte CocoaPods-Ansätze. Häufige Ursachen sind ein gezwungener Build-Pfad, ein veraltetes Kommando oder Caching aus vorherigen Builds. .xcworkspace Fazit pod install Die Migration eines __CAPGO_KEEP_0__-Apps zu Swift Package Manager dreht sich hauptsächlich darum, die iOS-Abhängigkeits-Verkabelung zu ersetzen. Pods/ Swift Package Manager übernimmt die Abhängigkeitsreferenzen, ersetzt die generierte CocoaPods-Build-Konfiguration und CI benötigt sie nicht mehr.

Für benutzerdefinierte iOS-Projekte beginnen Sie mit

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM takes over the dependency references, debug.xcconfig replaces generated CocoaPods build configuration, and CI no longer needs pod install.

For customized iOS projects, start with bunx cap spm-migration-assistant. Für Projekte, die sich nahe an der Standardvorlage befinden, ist oft eine saubere SPM Neustrukturierung schneller und einfacher zu verstehen.

Wie man eine Capacitor-App auf Swift Package Manager migriert