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

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

Wie Sie jetzt migrieren

CocoaPods ist auf dem Weg, sich in einen lesenden Trunk zu verwandeln. Derzeit ist der Plan, dass der CocoaPods-Trunk aufhört, neue Podspezifikationen zu akzeptieren, am Dezember 2, 2026. Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsupdates, die auf trunk basieren, 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 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 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 Ihre native iOS-Plugin-Abhängigkeiten referenziert. Die Capacitor CLI-Updates CapApp-SPM werden, wenn Sie Plugins synchronisieren, daher behandeln Sie es als generiertes Ausgabe und vermeiden es, es manuell zu bearbeiten.

debug.xcconfig ersetzt die Pods-Konfiguration

Migrierungsassistent erstellt auch ein generiertes debug.xcconfigDieses 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 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-converterkonvertiert werden, aber Plugins mit komplexeren Objective-C- und Swift-Anordnungen benötigen möglicherweise manuelle Arbeit.

Was zuerst sichern

Beginnen Sie mit einer leeren 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 Sie aus ios/App/ beachten sollten:

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
Signierungs-Einstellungen, Bundle-Identifier, Team-ID und Profil-Einstellungen

Behalten Sie auch alle native Swift, Objective-C, Frameworks, Erweiterungen oder SDK-Dateien, die Sie außerhalb des Standard-Capacitor-Templates hinzugefügt haben.

Option 1: Nutzen Sie den Capacitor-Migration-Assistenten

Nutzen Sie diesen Weg, wenn Ihre iOS-Projekt benutzerdefinierte native Änderungen enthält, die Sie nicht verlieren möchten.

Führen Sie den Assistenten von der Wurzel 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 Assistent entfernt die CocoaPods-Infrastruktur, erstellt die lokale Paketdatei, generiert Paketverweise aus Ihren installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien.

bunx cap open ios

Dann folgen Sie den manuellen Xcode-Schritten, die vom Assistenten ausgegeben werden. In den meisten Projekten bedeutet dies:

Add CapApp-SPM als lokale Paketabhaengigkeit hinzufügen.
Die generierte debug.xcconfig zum Anwendungs-Konfiguration hinzufügen.
Beheben Sie alle Warnungen ueber Plugins, die nicht in SPM umgewandelt werden konnten.
Das Anwendungs-Programm aus Xcode einmal vor dem Aktualisieren der CI erstellen.

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

bunx cap sync ios

Option 2: Das iOS-Projekt mit SPM neu aufbauen

Verwenden Sie diesen Weg, wenn Ihr ios/ Verzeichnis sich nahe an der Standard-Capacitor-Vorlage befindet und Sie sicherstellen können, dass die benutzerdefinierten Dateien danach wiederhergestellt werden können.

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

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

Richten Sie die native Dateien, die Ihre App benötigt, und öffnen Sie dann das Projekt:

bunx cap open ios

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

Aktualisieren Sie CI nach der Migration

Sobald die App lokal kompiliert ist, aktualisieren Sie CI/CD, damit sie nicht mehr CocoaPods annehmen kann.

Entfernen Sie Schritte, die ausführen:

pod install

Entfernen Sie auch 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-Ressourcen 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.
Kommentieren Sie die aktuelle Arbeitsanwendung.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Führen Sie die benutzerdefinierten iOS-Dateien und Signierungs-Einstellungen auf.
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.
Appspezifische 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 der CI entfernen.
Überprüfen, ob die Veröffentlichungsunterzeichnung noch funktioniert.
Bevor Sie die App veröffentlichen, sollten Sie sie auf mindestens einem Simulator und einem realen Gerät ausführen.

Fehlerbehebung

Wenn Xcode die Pakete nicht auflösen kann, sollten Sie die Paket-Caches in Xcode zurücksetzen und ausführen. 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-Ansätze. Häufige Ursachen sind ein gezwungener Build-Pfad, ein veraltetes Kommando oder Caching aus vorherigen Builds. .xcworkspace Zusammenfassung pod install Die Migration einer __CAPGO_KEEP_0__-App zum Swift Package Manager dreht sich hauptsächlich darum, die iOS-Abhängigkeitsverkabelung zu ersetzen. Pods/ übernimmt die Abhängigkeitsreferenzen,

ersetzt die generierte CocoaPods-Buildkonfiguration und CI benötigt

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Für Projekte, die sich der Standardvorlage nähern, ist oft eine saubere SPM-Wiederherstellung schneller und einfacher zu verstehen. debug.xcconfig builds pod install.

assumptions bunx cap spm-migration-assistantcaching

Ressourcen

Fortsetzen 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 und zu verbinden, wenden Sie sich an Capgo Enterprise um das Produktworkflow in Capgo Enterprise Ionische Unternehmens-Plugin-Alternativen 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 für das Produktworkflow in Capgo Premium Support.

Wie Sie eine Capacitor-App auf Swift Package Manager migrieren