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 Ihrer App ab.

Diese Anleitung führt durch die Änderungen, was zu sichern ist und die beiden praktischen Migrationen: die Verwendung des Capacitor-Migrationsassistenten oder die Neustrukturierung des iOS-Projekts mit SPM.

Warum jetzt migrieren

CocoaPods ist auf den Weg, die Trunk-Verwaltung zu einem Lesen-Verboten-Modus umzustellen. Der aktuelle Plan ist, dass die CocoaPods-Trunk-Verwaltung neue Podspecs nicht mehr akzeptieren wird Dezember 2, 2026Bestehende Builds sollten weiterhin funktionieren, aber neue Veröffentlichungen und Abhängigkeitsaktualisierungen, die auf trunk angewiesen sind, 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 oder SPM und Capacitor 8 erstellt nun iOS-SPM-Projekte als Standardvorlage.

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

Das Umstellen 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 an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM . Diese Paketdatei wird zum zentralen Ort, an dem __CAPGO_KEEP_0__ auf Ihre native iOS-Plugin-Abhängigkeiten verweist. Die __CAPGO_KEEP_1__ __CAPGO_KEEP_2__-Aktualisierungen

werden, wenn Sie Plugins synchronisieren, aktualisiert, daher behandeln Sie es als generiertes Ausgabe und vermeiden es, es manuell zu bearbeiten. Das debug.xcconfig ersetzt die Pods-Konfiguration.

The Migrations-Assistent erstellt auch eine generierte Datei debug.xcconfig. Diese Datei enthält die Build-Einstellungen, die CocoaPods früher durch seine generierten xcconfig-Dateien 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-converter, aber Plugins mit komplexeren Objective-C- und Swift-Anordnungen benötigen möglicherweise manuelle Arbeit.

Was zuerst sichern

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

Gemeinsame Dateien, die Sie aus ios/App/ behalten sollten, umfassen:

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
Zertifizierungseinstellungen, Bundle-Bezeichner, Team-ID und Zertifizierungsprofil-Einstellungen

Halten 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 Ihr 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 Wenn er fertig ist, öffnen Sie das Projekt:

Die __CAPGO_KEEP_0__-Dateien werden nicht berührt.

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 Abhängigkeit des Pakets.
Fügen Sie die generierte debug.xcconfig der Anwendungskonfiguration hinzu.
Beheben Sie alle Warnungen über Plugins, die nicht in SPM umgewandelt werden konnten.
Bauen Sie die Anwendung aus Xcode einmal vor der Aktualisierung von CI.

Nachdem das Xcode-Projekt erstellt wurde, synchronisieren Sie sich erneut:

bunx cap sync ios

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

Verwenden Sie diesen Pfad, wenn Ihr ios/ Verzeichnis sich in der Nähe der Standardvorlage Capacitor befindet und Sie sicherstellen können, dass die benutzerdefinierten Dateien danach wiederhergestellt werden können.

Stellen Sie zunächst sicher, dass die in der Sicherung aufgeführten Dateien eingereicht oder an einem sicheren Ort kopiert wurden. Dann entfernen und erneut erstellen Sie den iOS-Projekt mit SPM:

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

Die native Dateien, die Ihre App benötigt, wiederherstellen, und dann das Projekt öffnen:

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 Kompromiss besteht darin, dass Sie die Signierung, die Berechtigungen, die Firebase-Dateien, die native Quellcodeänderungen und jede benutzerdefinierte Xcode-Einstellung sorgfältig wiederherstellen müssen.

Neue Capacitor Apps

Bei einer neuen 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

CI nach der Migration aktualisieren

Einmal das lokale Build-Projekt aktualisiert, CI/CD so aktualisieren, dass es nicht mehr davon ausgeht, dass CocoaPods verwendet wird.

Schritte entfernen, die ausgeführt werden:

pod install

Auch Caches für entfernen:

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

Behalten Sie Ihre reguläre Web-Build- und Capacitor-Synchronisierungsschritte bei. Ein typischer iOS-Job sollte 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 eine neue Git-Branche.
Kommentieren Sie die aktuelle Arbeitsanwendung.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Speichern Sie benutzerdefinierte iOS-Dateien und Signierungseinstellungen.
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 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

Wenn Xcode Pakete nicht auflösen kann, stellen Sie die Paket-Caches in Xcode zurück und führen Sie sie aus. bunx cap sync ios wieder.

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 unterhalten, migrieren Sie das Plugin-Paket zuerst und kehren dann zur App-Migration zurück.

Wenn die App lokal gebaut wird, aber CI fehlschlägt, überprüfen Sie alte CocoaPods-Anschlüsse. Häufige Ursachen sind ein gezwungener Build-Pfad, ein veraltetes Kommando oder Caching aus vorherigen Builds. .xcworkspace Zusammenfassung pod install Die Migration eines __CAPGO_KEEP_0__-Apps zu Swift Package Manager dreht sich hauptsächlich um die Ersetzung der iOS-Abhängigkeitsverkabelung. Pods/ SPM übernimmt die Abhängigkeitsreferenzen, ersetzt die generierte CocoaPods-Buildkonfiguration und CI benötigt sie nicht mehr.

Für individuell angepasste iOS-Projekte beginnen Sie mit

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM wieder. debug.xcconfig 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 unterhalten, migrieren Sie das Plugin-Paket zuerst und kehren dann zur App-Migration zurück. pod install.

Ressourcen

Weitermachen von Wie Sie eine Capacitor-App auf den Swift Package Manager migrieren

Wenn Sie __CAPGO_KEEP_0__ verwenden Wie Sie eine Capacitor-App auf den Swift Package Manager migrieren Um die Migration und die Unternehmensoperationen zu planen, verbinden Sie es mit Capgo Enterprise für den Produktworkflow in Capgo Enterprise Alternativen zu Ionic Enterprise Plugins für das Produktworkflow in Ionic Enterprise Plugin Alternativen Capgo Alternativen für das Produktworkflow in Capgo Alternativen Capgo Consulting für das Produktworkflow in Capgo Consulting und Capgo Premium Support for the product workflow in Capgo Premium Support.

Wie man eine Capacitor-Anwendung auf Swift Package Manager migriert