Wie migriert man eine Capacitor-Anwendung zum Swift Package Manager

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

Diese Anleitung führt Sie durch die Änderungen, die Sie sichern sollten und die beiden praktischen Migrationen: die Verwendung des Capacitor-Migrationsassistenten oder die Neukonfiguration des iOS-Projekts mit SPM.

Warum jetzt migrieren

CocoaPods ist auf den Weg, den Hauptzweig zu einem Lesen- nur-Zweig zu machen. Der aktuelle Plan ist, dass der CocoaPods-Hauptzweig ab dem 2. Dezember 2026nicht mehr neue Podspezifikationen akzeptiert. Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsaktualisierungen, die auf den Hauptzweig verweisen, werden dort nicht mehr veröffentlicht.

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 in einem Capacitor-SPM-Projekt

Migrieren Sie von CocoaPods zu SPM ersetzt die iOS-Abhängigkeitslayer. Die Webanwendung, das Android-Projekt und die meisten Capacitor-Workflow-Befehle bleiben gleich.

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 ein lokales Paket mit dem Namen CapApp-SPMDieses Paket wird zum zentralen Ort, an dem Capacitor auf Ihre native iOS-Plugin-Abhängigkeiten verweist. Der Capacitor CLI wird CapApp-SPM Wenn Sie Plugins synchronisieren, wird es aktualisiert, daher behandeln Sie es als generiertes Ausgabe und vermeiden Sie es, es manuell zu bearbeiten.

debug.xcconfig ersetzt die Pods-Konfiguration

Der Migration-Assistent erstellt auch eine generierte debug.xcconfigDieses Datei trägt Build-Einstellungen, die CocoaPods durch seine generierten xcconfig-Dateien bereitgestellt hat.

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-converteraber Plugins mit komplexeren Objective-C- und Swift-Layouts 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 nativeen Dateien auf, auf die Ihre App angewiesen ist.

Gemeinsame Dateien, die Sie aufbewahren sollten von 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
Signingsettings, Bundle-Identifikator, Team-ID und Provisioning-Profile-Einstellungen

Auch bewahren Sie alle native Swift-, Objective-C-, Framework-, Erweiterungs- 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.

Laufen 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:

Dann folgen Sie den manuellen Xcode-Schritten, die der Assistent ausgegeben hat. In den meisten Projekten bedeutet dies:

bunx cap open ios

Hinzufügen

als lokale Paketabhaengigkeit. CapApp-SPM Hinzufügen der generierten
als lokale Paketabhaengigkeit. debug.xcconfig zur Anwendungskonfiguration.
Lösen 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 noch einmal:

bunx cap sync ios

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

Verwenden Sie diesen Pfad, wenn Ihr Verzeichnis nahe an der Standard-__CAPGO_KEEP_0__-Vorlage liegt und Sie Ihre benutzerdefinierten Dateien sicher wiederherstellen können. ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

Wiederherstellen Sie die native Dateien, die Ihre Anwendung benötigt, und öffnen Sie dann das Projekt:

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

Diese Methode ist oft sauberer als eine in-Place-Migration, da sie Ihnen einen frischen __CAPGO_KEEP_0__-8-iOS-Vorlagen bietet. Der Nachteil ist, dass Sie sorgfältig die Signierung, die Berechtigungen, die Firebase-Dateien, die native Quellcodeänderungen und die benutzerdefinierten Xcode-Einstellungen wiederherstellen müssen.

bunx cap open ios

Neue Capacitor-Anwendungen

Bei einer neuen Anwendung verwendet Capacitor-8 SPM standardmäßig, wenn Sie iOS hinzufügen.

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

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

bunx cap add ios --packagemanager SPM

CI nach Migration aktualisieren

Sobald die App lokal gebaut wird, aktualisieren Sie CI/CD, sodass sie nicht mehr davon ausgeht, dass CocoaPods verwendet wird.

Schritte entfernen, die laufen:

pod install

Auch entfernen Sie 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

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:

Einen neuen Git-Zweig erstellen.
Die aktuelle Arbeits-App committen.
Überprüfen Sie, ob jeder installierte Plugin SPM unterstützt.
Benennen Sie benutzerdefinierte iOS-Dateien und Signatur-Einstellungen.
Bestätigen Sie, dass die App vor der Migration erstellt wurde.

Während der Migration:

Ausführen bunx cap spm-migration-assistant oder neu aufbauen ios/.
Hinzufügen CapApp-SPM in Xcode erforderlich.
Hinzufügen debug.xcconfig in Xcode erforderlich.
Wiederherstellen von App-spezifischen nativen Dateien.
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 Freigabe-Zertifizierung noch funktioniert.
Die App auf mindestens einem Simulator und einem realen Gerät vor der Veröffentlichung ausführen.

Fehlersuche

Wenn Xcode die Pakete nicht auflösen kann, löschen Sie die Paket-Caches von Xcode und führen Sie den Vorgang bunx cap sync ios wiederholen.

Wenn die Migration aufgrund eines Plugins scheitert, ü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 zum App-Migration zurück.

Wenn die App lokal gebaut wird, aber CI scheitert, suchen Sie nach alten CocoaPods-Anschlüssen. Häufige Ursachen sind ein gezwungener .xcworkspace Build-Pfad, ein veraltetes pod install Befehl oder Caching Pods/ aus vorherigen Builds.

Fazit

Ein Capacitor-Projekt auf Swift Package Manager umzustellen ist hauptsächlich darum, die iOS-Abhängigkeitsverkabelung zu ersetzen. CapApp-SPM übernimmt die Abhängigkeitsverweise, debug.xcconfig ersetzt die generierte CocoaPods-Buildkonfiguration und CI benötigt pod install.

Für benutzerdefinierte iOS-Projekte beginnen Sie mit bunx cap spm-migration-assistant. Für Projekte, die sich nahe an der Standardvorlage befinden, ist eine saubere SPM-Wiederherstellung oft schneller und einfacher zu verstehen.

Ressourcen

Weitermachen von How to Migrieren Sie eine Capacitor-Anwendung zum Swift Package Manager

Wenn Sie __CAPGO_KEEP_0__ verwenden Wie Sie eine Capacitor-Anwendung zum 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 Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen Capgo Alternativen für den Produktworkflow in Capgo Alternativen Capgo Consulting für den Produktworkflow in Capgo Consulting, und Capgo Premium Support für den Produktworkflow in Capgo Premium Support.

Wie man eine Capacitor-Anwendung auf Swift Package Manager migriert