Wie migriert man eine Capacitor-Anwendung 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 sich ebenfalls migrieren, aber der sichere Weg hängt von der Menge an nativen iOS-Anpassungen in Ihrer App ab.

Diese Anleitung führt Sie durch die Änderungen, die Sie sichern sollten und die beiden praktischen Migrationsschritte: 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 Dezember 2, 2026abgeschaltet wird. 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 iOS-SPM-Projekte als Standardtemplate.

Was ändert sich in einem Capacitor-SPM-Projekt

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

CapApp-SPM ersetzt das Podfile

In einer CocoaPods-App werden iOS-Abhängigkeiten über ios/App/Podfile, Podfile.lock, Pods/, und das 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 auf Ihre native iOS-Plugin-Abhängigkeiten verweist. Die Capacitor CLI wird CapApp-SPM wenn Sie Plugins synchronisieren, also behandeln Sie es als generierte Ausgabe und vermeiden es, es manuell zu bearbeiten.

debug.xcconfig ersetzt die Pods-Konfiguration

Der Migration-Assistent erstellt auch eine generierte debug.xcconfig. Diese Datei enthält 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 kombinieren. 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-converterumgewandelt werden, aber Plugins mit komplexeren Objective-C- und Swift-Layouts 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 Dateien auf, auf die Ihre App angewiesen ist.

Gemeinsame Dateien, die beibehalten werden sollten von ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, wenn Ihre App eins hat
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, wenn Sie Firebase verwenden
Benutzerdefiniert .xcconfig Dateien
Zertifizierungseinstellungen, Bundle-Identifier, Team-ID und Provisioning-Profile-Einstellungen

Beibehalten 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 es fertig ist, öffnen Sie das Projekt:

Folgen Sie dann den manuellen Xcode-Schritten, die der Assistent ausgibt. In den meisten Projekten bedeutet dies:

bunx cap open ios

Hinzufügen

als lokale Paketabhaengigkeit. CapApp-SPM Hinzufügen der generierten
zur Anwendungs-Konfiguration. debug.xcconfig Beheben Sie alle Warnungen über Plugins, die nicht in SPM umgewandelt werden konnten.
Bauen Sie die Anwendung aus Xcode einmal, bevor Sie die CI aktualisieren.
Nachdem die Xcode-Projektdatei erstellt wurde, synchronisieren Sie sich erneut:

Hinweis: Die Anweisungen können je nach Projekt variieren.

bunx cap sync ios

Option 2: Das iOS-Projekt mit SPM neu aufbauen

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

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

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

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

bunx cap open ios

Diese Methode ist oft sauberer als eine in-Place-Migration, da sie Ihnen ein frisches Capacitor 8 iOS-Vorlage bietet. Der Nachteil ist, dass Sie sorgfältig die Signierung, die Berechtigungen, die Firebase-Dateien, die native Quellcodeänderungen und die benutzerdefinierten Xcode-Einstellungen neu anwenden 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

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

Entfernen Sie Schritte, die CocoaPods ausführen:

pod install

Also entfernen Sie Caches für:

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

Halten Sie Ihre reguläre Web-Build- und Capacitor-Synchronisierungs-Schritte. 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 jeder installierte Plugin SPM unterstützt.
Aufzeichnen Sie benutzerdefinierte iOS-Dateien und Signierungs-Einstellungen.
Bestätigen Sie, dass die App vor der Migration gebaut wird.

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.
App-spezifische native Dateien wiederherstellen.
Ausführen bunx cap sync ios.

Nach der Migration:

Die App in Xcode erstellen und ausführen.
Überbleibene CocoaPods-Dateien entfernen.
Entfernen pod install aus CI.
Überprüfen Sie, ob die Signatur der Veröffentlichung noch funktioniert.
Bevor Sie das Produkt auf den Markt bringen, sollten Sie das App auf mindestens einem Simulator und einem realen Gerät ausführen.

Fehlersuche

Wenn Xcode die Pakete nicht auflösen kann, stellen Sie die Paket-Caches von Xcode zurück und führen Sie das Kommando erneut aus. bunx cap sync ios 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 selbst entwickeln, sollten Sie das Plugin-Paket zuerst migrieren und dann zurück zur App-Migrationkehren.

Wenn das App lokal gebaut wird, aber die CI-Funktion fehlschlägt, überprüfen Sie nach alten CocoaPods-Anschlüssen. Häufige Ursachen sind ein gezwungener Build-Pfad, ein veraltetes Kommando oder Caching aus vorherigen Builds.

Zusammenfassung .xcworkspace Die Migration einer __CAPGO_KEEP_0__-App auf Swift Package Manager dreht sich hauptsächlich um die Ersetzung der iOS-Abhängigkeits-Verkabelung. pod install Troubleshooting Pods/ If Xcode cannot resolve packages, reset package caches from Xcode and run again.

If the migration fails because of a plugin, check whether the plugin has a newer release with SPM support. For plugins you maintain, migrate the plugin package first and then return to the app migration.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM übernimmt die Abhängigkeitsreferenzen, 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 der Standardvorlage nahe kommen, ist eine saubere SPM-Wiederherstellung oft schneller und einfacher zu verstehen.

Ressourcen

Weitermachen von How to Migrate a Capacitor App zu Swift Package Manager

Wenn Sie How to Migrate a Capacitor App zu Swift Package Manager für die Planung der Migration und Unternehmensoperationen, verbinden Sie es mit Capgo Unternehmenslösung für den Produktworkflow in Capgo Unternehmenslösung Alternativen zum Ionic Enterprise Plugin für den Produktworkflow in Alternativen zum Ionic Enterprise Plugin Capgo Alternativen für den Produktworkflow in Capgo Alternativen Capgo Beratung für den Produktworkflow in Capgo Beratung und Capgo Premium-Support für den Produktworkflow in Capgo Premium-Support.

Wie man eine Capacitor-App auf Swift Package Manager migriert