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 migriert werden, aber der sichere Weg hängt von der Menge an nativen iOS-Anpassungen in der App ab.

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

Warum migrieren Sie jetzt?

CocoaPods ist auf dem Weg, den Trunk zu einem Lesen- nur-Verzeichnis zu machen. Derzeit ist geplant, dass CocoaPods-Trunk am 2. Dezember 2026Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsaktualisierungen, die auf trunk angewiesen sind, werden dort nach der Umstellung 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.

Was ändert sich in einer Capacitor-SPM-Projekt

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

CapApp-SPM ersetzt die Podfile

In einer CocoaPods-Anwendung 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.xcconfigDiese 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 zur Xcode-Projekt-Konfiguration, wenn der Assistent Sie dazu auffordert.

Jeder Plugin muss SPM unterstützen

You können CocoaPods und SPM nicht in einem 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 Ionics capacitor-plugin-converter, aber 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 native Dateien auf, auf die Ihre App angewiesen ist.

Gemeinsame Dateien, die Sie aus dem ios/App/ einschließen:

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
Custom .xcconfig context
Zertifizierungseinstellungen, Bundle-Identifikator, Team-ID und Bereitstellungprofil-Einstellungen

Behalten Sie auch 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-Migrationsassistenten.

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 CapApp-SPM Paket, generiert Paketverweise aus Ihren installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien.

Wenn es fertig ist, öffnen Sie das Projekt:

bunx cap open ios

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

Add CapApp-SPM Hinzufügen der generierten
zur Anwendungs-Konfiguration. debug.xcconfig zur App-Konfiguration.
Beheben Sie alle Warnungen über Plugins, die nicht in SPM umgewandelt werden konnten.
Bauen Sie die App einmal aus Xcode, bevor Sie CI aktualisieren.

After the Xcode project builds, sync again:

bunx cap sync ios

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

Verwenden Sie diesen Pfad, wenn Ihr ios/ Verzeichnis ist nah an der Standardvorlage von Capacitor und Sie können Ihre benutzerdefinierten Dateien sicher danach wiederherstellen.

First, make sure the files listed in the backup section are committed or copied somewhere safe. Then remove and recreate the iOS project with SPM:

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

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

bunx cap open ios

This path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, and any custom Xcode settings.

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

CI aktualisieren nach der Migration

Sobald die App lokal gebaut wird, aktualisieren Sie CI/CD, damit sie CocoaPods nicht mehr annehmen sollte.

Löschen Sie Schritte, die ausführen:

pod install

Auch löschen 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

Halten Sie Ihre reguläre Web-Build- und Capacitor-Synchronisierungsschritte bei. 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

Migrationscheckliste

Bevor die Migration:

Einen neuen Git-Zweig erstellen.
Die aktuelle Arbeitsanwendung committen.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Kundeneinstellungen für iOS-Dateien und Signierung aufzeichnen.
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/.
Add CapApp-SPM in Xcode wenn erforderlich.
Add debug.xcconfig in Xcode wenn erforderlich.
App-spezifische native Dateien wiederherstellen.
Ausführen bunx cap sync ios.

Wiederherstellen Sie native App-Dateien.

Nach der Migration: Die App in Xcode erstellen und ausführen.
Überbleibene CocoaPods-Dateien entfernen.
Entfernen pod install aus CI.
Verify release signing still works.
Laufen Sie die App auf mindestens einem Simulator und einem realen Gerät, bevor Sie sie verschicken.

Troubleshooting

Wenn Xcode die Pakete nicht auflösen kann, rufen Sie die Paket-Caches von Xcode auf und führen Sie aus bunx cap sync ios 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.

Wenn die App lokal baut, aber CI fehlschlägt, überprüfen Sie alte CocoaPods-Ansätze. Häufige Ursachen sind ein gezwungener .xcworkspace Pfad zum Bauen, ein veraltetes pod install Build-Pfad, ein veralteter Befehl oder Caching Pods/ aus vorherigen Builds.

Zusammenfassung

Die Migration einer Capacitor-App in den Swift Package Manager dreht sich hauptsächlich um die Ersetzung der iOS-Abhängigkeitsverkabelung. 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 sich der Standardvorlage nähern, ist eine saubere SPM-Wiederherstellung oft schneller und einfacher zu verstehen.

Ressourcen

Weiter von Wie man eine Capacitor-App auf Swift Package Manager migriert

Wenn Sie __CAPGO_KEEP_0__ verwenden Wie man eine Capacitor-App auf Swift Package Manager migriert zum Planen der Migration und Unternehmensoperationen, 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 Beratung für den Produktworkflow in Capgo Consulting Capgo Premium Support zum Produktworkflow in Capgo Premium Support.