Wie migriert man eine Capacitor-Anwendung zum Swift Package Manager

Swift Package Manager ist die Standardrichtung für Capacitor iOS-Projekte. Wenn Ihre App noch CocoaPods verwendet, können Sie die App selbst ohne Wiederaufbau Ihres JavaScript-code-, Android-Projekts oder der Veröffentlichungsworkflow von vorneherein auf SPM umstellen.

Diese Anleitung ist für App-Teams gedacht. Sie erklärt, wie Sie eine Capacitor-iOS-App von CocoaPods auf SPM umstellen, was der Migration-Assistent ändert, was Sie noch in Xcode überprüfen müssen und wie Sie den CI nach der App-Bereitung aufräumen.

Was ändert sich im App

Eine CocoaPods-basierte Capacitor-App hängt von Dateien wie:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Eine SPM-basierte Capacitor-App verlagert die iOS-Abhängigkeitsverkabelung in den Swift Package Manager. Während der Migration erstellt Capacitor eine lokale Paketdatei mit dem Namen CapApp-SPM und verwendet sie, um die App-Ziel mit Capacitor und installierten nativen Abhängigkeiten zu verbinden.

Die Web-Build-Arbeit funktioniert weiterhin auf die gleiche Weise. Sie führen weiterhin eine Web-Build-Arbeit durch, synchronisieren Capacitor, öffnen Xcode und archivieren die App. Die Hauptsache ist, dass CocoaPods die iOS-Abhängigkeitsgraphik nicht mehr besitzt.

Bevor Sie migrieren

Beginnen Sie mit einer sauberen Zweig und stellen Sie sicher, dass die aktuelle App vor der Änderung der Abhängigkeitsmanager erfolgreich kompiliert wird:

git status
npm run build
npx cap sync ios

Dann committen Sie den Arbeitszustand. Die Migration berührt generierte iOS-Projektdateien, daher ist es wichtig, einen sauberen Rollback-Punkt zu haben.

Als Nächstes überprüfen Sie, was Ihre App unter ios/App/besonders bearbeitet hat. Gemeinsame Dateien und Einstellungen, die Sie aufbewahren sollten, umfassen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, wenn vorhanden
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, wenn Sie Firebase verwenden
Benutzerdefiniert .xcconfig Dateien
Einstellungen für die Signierung, Bundle-Identifier, Team-ID und Provisioning-Profiles
App-Erweiterungen, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

Überprüfen Sie auch Ihre installierten Capacitor und Cordova-Abhängigkeiten. Eine App-Level-Migration kann durch eine native Abhängigkeit blockiert werden, die keinen SPM-kompatiblen Pfad hat. Aktualisieren Sie diese Pakete, wenn möglich, bevor Sie migrieren.

Verwenden Sie den Migration-Assistenten

Für die meisten bestehenden Apps beginnen Sie mit dem offiziellen Capacitor-Migration-Assistenten:

npx cap spm-migration-assistant

Starten Sie es vom Root-Verzeichnis Ihres Capacitor-Projekts aus. Der Assistent entfernt die CocoaPods-Integration, erstellt das lokale Paket, generiert Paketverweise für installierte native Abhängigkeiten und fügt die erforderliche Konfiguration hinzu, die durch das iOS-Projekt benötigt wird. CapApp-SPM Nachdem es fertig ist, öffnen Sie das iOS-Projekt:

Wenn Sie Firebase verwenden, sollten Sie auch Ihre Firebase-Abhängigkeiten aktualisieren, bevor Sie migrieren.

npx cap open ios

Lesen Sie die Ausgabe des Assistenten, bevor Sie Ihr Terminal schließen. Wenn es Sie auffordert, manuelle Xcode-Schritte abzuschließen, tun Sie das, bevor Sie sich erneut synchronisieren.

Fertigstellen Sie die Xcode-Schritte

In Xcode überprüfen Sie die Anwendungsvorlage und die Zielkonfiguration:

Bestätigen CapApp-SPM wird als lokales Paketabhaengigkeit hinzugefuegt.
Bestätigen Sie, dass die Anwendungsvorlage die generierten Paketprodukte verlinkt.
Fügen Sie das generierte debug.xcconfig zur Projekt-Konfiguration, wenn der Assistent danach fragt.
Lösen Sie alle Paketwarnungen in Xcode.
Bauen Sie die Anwendung einmal aus Xcode.

Wenn Xcode die Pakete nicht lösen kann, verwenden Sie Datei > Pakete > Paket-Caches zurücksetzen Dann lösen Sie die Pakete erneut auf.

Sync und bauen Sie erneut

Nachdem Xcode konfiguriert wurde, kehren Sie in die Terminal-Anwendung zurück und synchronisieren Sie Capacitor:

npx cap sync ios

Dann bauen Sie von Xcode aus erneut. Behandeln Sie die Migration nicht als abgeschlossen, bis ein sauberer Build von Xcode funktioniert, da die Freigabezertifizierung, die Berechtigungen, die App-Erweiterungen und die Paketresolución dort validiert werden.

Wenn die App Push-Benachrichtigungen, verbundene Domains, Hintergrundmodi, App-Gruppen, Firebase oder jede native SDK-Konfiguration verwendet, führen Sie diese Flows auf einem Simulator oder Gerät aus, nachdem der Build erfolgreich war.

Alternative: Erstellen Sie iOS mit SPM neu

Wenn Ihr ios/ Ordner sich der Standard- Capacitor-Vorlage annähert, kann es schneller sein, ihn mit SPM neu zu erstellen, anstatt ihn an Ort und Stelle zu migrieren.

Verwenden Sie nur diesen Weg, nachdem Sie alle native Dateien und Signierungseinstellungen, die Sie benötigen, abgespeichert oder gesichert haben:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Dann laden Sie Ihre app-spezifischen native Dateien und Einstellungen wieder her. Dieser Weg gibt Ihnen ein sauberes SPM-Projekt, aber es ist einfacher, wenn Sie nicht vorher Ihre Xcode-Änderungen inventarisiert haben, Ihre benutzerdefinierten Xcode-Änderungen zu verlieren.

Für neue Capacitor-Apps erstellt Capacitor 8 iOS-Projekte mit SPM standardmäßig:

npx cap add ios

Sie können immer noch explizit sein:

npx cap add ios --packagemanager SPM

Überbleibsel von CocoaPods entfernen

Nachdem die SPM-Anwendung gebaut wurde, entfernen Sie die CocoaPods-Voraussetzungen aus lokalen Skripten und CI.

Schritte wie:

pod install

Auch entfernen Sie Caches, die nur für CocoaPods existierten:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods-Spezifikations-Repositories
CI-Cache-Schlüssel basierend auf dem Podfile

Ein grundlegender CI-Flow nach der Migration sollte JavaScript-Abhängigkeiten installieren, die Web-App bauen, Capacitor synchronisieren und mit Xcode bauen:

npm ci
npm run build
npx cap sync ios

Wenn Ihr CI immer noch baut App.xcworkspace, aktualisieren Sie es auf den Projekt- oder Workspace-Pfad, der nach der Migration existiert. Halten Sie keine veralteten CocoaPods-Pfade auf, nur weil der alte Job sie verwendet hat.

Hilfe bei Problemen

Der Assistent warnt vor einem inkompatiblen Abhängigkeit

Ersetzen Sie die Abhängigkeit zuerst und führen Sie den Assistenten erneut aus. Wenn keine SPM-kompatiblen Version existiert, lassen Sie die App auf CocoaPods, bis Sie die Abhängigkeit ersetzen oder der Maintainer SPM-Unterstützung hinzufügt.

Xcode kann Pakete nicht auflösen

Lösche die Paket-Caches in Xcode, überprüfe, dass CapApp-SPM ist als lokales Paket vorhanden und führe npx cap sync ios wieder aus.

Die App baut lokal, aber CI fehlschlägt

Suche nach alten CocoaPods-Voraussetzungen: pod install, Pods/ Caches, Podfile.lock Cache-Schlüssel oder Build-Befehle, die auf einen gelöschten .xcworkspace.

Signierung oder Berechtigungen geändert

Vergleiche das migrierte Xcode-Ziel mit dem Projekt vor der Migration. Richte den Bundle-Identifier, Team, Provisioning-Profil, Berechtigungen-Datei, Fähigkeiten und Erweiterungseinstellungen wieder her.

Migrationscheckliste

Vor der Migration:

Erstelle einen Zweig.
Bestätige, dass die aktuelle iOS-Anwendung kompiliert wird.
Füge die Arbeitsschritte hinzu.
Überprüfe die benutzerdefinierten native Dateien und Signierungseinstellungen.
Aktualisiere native Abhängigkeiten, die bereits neuere SPM-kompatible Releases haben.

Während der Migration:

Ausführen npx cap spm-migration-assistant.
Öffne das Projekt mit npx cap open ios.
Hinzufügen CapApp-SPM in Xcode erforderlich, wenn.
Hinzufügen debug.xcconfig in Xcode erforderlich, wenn.
Löse Paketwarnungen.
Run npx cap sync ios.

Nach der Migration:

Bauen Sie die App aus Xcode.
Testen Sie native Funktionen auf einem Simulator oder Gerät.
Entfernen Sie CocoaPods-Befehle aus CI.
Entfernen Sie CocoaPods-spezifische Caches.
Überprüfen Sie das Archiv- und Release-Zertifikat.

Verwenden Sie Capgo Fähigkeiten für die Migration

Wenn Sie AI-Agenten verwenden, um die Migration zu handhaben, beginnen Sie mit Capgo Fähigkeiten anstatt einem leeren Prompt. Die nützlichsten Fähigkeiten für diese Arbeit sind:

capacitor-best-practices vor der Änderung die App-Struktur zu überprüfen ios/.
cocoapods-to-spm die Migration des SPM und die Xcode-Folgeaufgaben zu planen
capacitor-ci-cd CocoaPods-Vorannahmen aus den Buildpipelines zu entfernen
debugging-capacitor und ios-android-logs nach der Migration Probleme mit Geräten nur zu untersuchen

Verwenden Sie sie, bevor Sie die iOS-Projekt ändern, damit der Agent native Dateien, CI und Abhängigkeiten überprüft, anstatt nur den Migration-Befehl auszuführen

Zusammenfassung

Die Migration eines Capacitor-Apps zu Swift Package Manager ist hauptsächlich eine Änderung der iOS-Abhängigkeitsverwaltung. Der sichere Weg ist, von einem sauberen Branch aus zu beginnen, zu laufen npx cap spm-migration-assistant, die manuellen Xcode-Schritte abzuschließen, noch einmal zu synchronisieren und CocoaPods aus CI nur nachdem das App baut

Wenn Ihr iOS-Projekt stark anpassungsfähig ist, migrieren Sie in Ordnung. Wenn es sich der Standard Capacitor-Template nähert, kann die Wiedererstellung ios/ mit npx cap add ios --packagemanager SPM sauberer sein

Wie Sie Ihre Capacitor-App auf Swift Package Manager migrieren