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

Dieses Leitfaden führt Sie durch die Änderungen, die Sicherung von Daten und die beiden praktischen Migrationswege: die Verwendung des Capacitor-Migrationsassistenten oder die Neukonfiguration des iOS-Projekts mit SPM.

Wozu 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 2026keine neuen Podspezifikationen mehr akzeptieren wird. Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsaktualisierungen, die auf den Hauptzweig angewiesen sind, 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 gibt es in einem Capacitor-SPM-Projekt?

Die Migration von CocoaPods zu SPM ersetzt das 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 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 auf Ihre native iOS-Plugin-Abhängigkeiten verweist. Die Capacitor CLI aktualisiert CapApp-SPM wenn Sie Plugins synchronisieren, daher 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 die Build-Einstellungen, die CocoaPods durch seine generierten xcconfig-Dateien bereitgestellt hat.

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

Jeder Plugin muss SPM unterstützen

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

und Cordova-Plugins in capacitor-plugin-converterWenn 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

Was zuerst sichern

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

Gemeinsame Dateien, die Sie aufbewahren sollten ios/App/ include:

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

Bewahren Sie auch alle native Swift-, Objective-C-, Framework-, Erweiterungs- oder SDK-Dateien auf, 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.

Starten Sie den Assistenten im Verzeichnis Ihres Capacitor-Projekts:

bunx cap spm-migration-assistant

Der Assistent entfernt die CocoaPods-Infrastruktur, erstellt das lokale Paket, generiert Paketverweise aus Ihren installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien. CapApp-SPM Wenn es fertig ist, öffnen Sie das Projekt:

Dann folgen Sie 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 App-Konfiguration. debug.xcconfig Beheben Sie alle Warnungen über Plugins, die nicht in SPM umgewandelt werden konnten.
Bauen Sie die App aus Xcode einmal, bevor Sie die CI aktualisieren.
Nachdem das Xcode-Projekt gebaut wurde, synchronisieren Sie erneut:

Hinzufügen

bunx cap sync ios

Option 2: Das iOS-Projekt mit SPM neu aufbauen

Verwenden Sie diesen Pfad, wenn Ihr Verzeichnis nah an der Standardvorlage __CAPGO_KEEP_0__ liegt und Sie die 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 erforderlichen native Dateien Ihres Apps, ö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 ein frisches __CAPGO_KEEP_0__ 8 iOS-Vorlage erhalten. Der Nachteil ist, dass Sie sorgfältig die Signierung, Berechtigungen, Firebase-Dateien, native Quellcodeänderungen und benutzerdefinierte Xcode-Einstellungen neu anwenden müssen.

bunx cap open ios

Neue Capacitor Apps

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

Update CI nach der Migration

bunx cap add ios --packagemanager SPM

Einmal das App lokal gebaut, aktualisieren Sie CI/CD, damit es nicht mehr CocoaPods annehmen sollte.

Entfernen Sie Schritte, die ausführen:

pod install

Entfernen Sie auch die 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-Ausgabe und Capacitor-Synchronisierungsschritte bei Laufzeit. Ein typischer iOS-Job sollte JavaScript-Abhängigkeiten installieren, die Web-Assets bauen, Capacitor synchronisieren und dann mit Xcode bauen:

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

Migration-Checkliste

Bevor die Migration:

Erstellen Sie einen neuen Git-Zweig.
Commiten Sie die aktuelle Arbeitsanwendung.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Führen Sie die benutzerdefinierten iOS-Dateien und Signierungseinstellungen auf.
Bestätigen Sie, dass die App vor der Migration erfolgreich kompiliert 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 bauen und ausführen.
Überbleibene CocoaPods-Dateien entfernen.
Entfernen pod install aus CI.
Überprüfen Sie, ob die Veröffentlichungsunterzeichnung noch funktioniert.
Laufen Sie die App auf mindestens einem Simulator und einem realen Gerät, bevor Sie sie verschicken.

Schwierigkeiten beim Aufrüsten

Seite/ Bereich: Unterstützung / Premium-Unterstützung oder Fußzeile-Unterstützungsabschnitt. Rolle: Abschnitts- oder Seitenüberschrift. Gesehen in: Seite support-policy.astro. Nachrichtenschlüssel `support_policy_troubleshooting_title` (Unterstützungspolitik - Schwierigkeiten beim Aufrüsten - Überschrift). bunx cap sync ios Wenn Xcode die Pakete nicht auflösen kann, stellen Sie die Paket-Caches von Xcode zurück und führen Sie ihn

erneut aus.

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 zur App-Migration zurück. .xcworkspace Wenn die App lokal gebaut wird, aber CI scheitert, überprüfen Sie nach alten CocoaPods-Anschlüssen. Häufige Ursachen sind ein gezwungener pod install Build-Pfad, ein veralteter Pods/ Befehl oder Caching

aus vorherigen Builds.

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 es nicht mehr pod install.

Für individuell angepasste 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

Fortsetzen Sie mit How to Migrate a Capacitor App to Swift Package Manager

Wenn Sie __CAPGO_KEEP_0__ verwenden Wie Sie eine Capacitor App auf Swift Package Manager migrieren um die Migration und die Unternehmensoperationen zu planen und zu verbinden mit Capgo Enterprise Capgo Enterprise Alternativen zum Ionic Enterprise Plugin __CAPGO_KEEP_0__ Alternativen Capgo Alternativen Capgo Consulting Capgo Consulting, und Capgo Premium Support Capgo Premium Support for the product workflow in Capgo Premium Support.

Wie man eine Capacitor-Anwendung auf Swift Package Manager migriert