Wie migriert man seine Capacitor App zu 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 auf SPM migrieren, ohne Ihre JavaScript-code-, Android-Projekt oder Release-Workflow von Grund auf neu aufzubauen.

Dieses Leitfaden ist für App-Teams gedacht. Es erklärt, wie Sie eine Capacitor-iOS-Anwendung von CocoaPods auf SPM migrieren, was die Migrationshilfe ändert, was Sie in Xcode noch überprüfen müssen und wie Sie CI nach der App-Building aufreinigen.

Was ändert sich in der App

Ein CocoaPods-basiertes Capacitor-Projekt hängt von Dateien wie:

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

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named CapApp-SPM and uses it to connect the app target with Capacitor and installed native dependencies.

und verwendet es, um die Zielanwendung mit Capacitor und den installierten nativen Abhängigkeiten zu verbinden.

Die Web-Build-Arbeit funktioniert immer noch auf die gleiche Weise. Sie führen immer noch eine Web-Build-Arbeit durch, synchronisieren __CAPGO_KEEP_0__, öffnen Xcode und archivieren die App. Der Hauptunterschied besteht darin, dass CocoaPods die iOS-Abhängigkeitsgraphik nicht mehr besitzt.

Bevor Sie migrieren

git status
npm run build
npx cap sync ios

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

Dann committen Sie den Arbeitszustand. Die Migration berührt die generierten iOS-Projektdateien, daher ist es wichtig, einen sauberen Rollbackpunkt zu haben. ios/App/Als Nächstes überprüfen Sie, was Ihre App unter

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftkundig gemacht hat. Häufige Dateien und Einstellungen, die erhalten bleiben sollten, sind:
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, wenn vorhanden
, wenn Sie Firebase verwenden .xcconfig benutzerdefiniert
signing-Einstellungen, Bundle-Identifier, Team-ID und Bereitstellungsprofile
App-Erweiterungen, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

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

Verwenden Sie die Migrations-Assistent

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

npx cap spm-migration-assistant

Ausführen Sie ihn 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 generierte Konfiguration hinzu, die für das iOS-Projekt erforderlich ist. CapApp-SPM Nachdem es fertig ist, öffnen Sie das iOS-Projekt:

Lesen Sie die Ausgabe des Assistenten, bevor Sie Ihren Terminal schließen. Wenn es Sie auffordert, manuelle Xcode-Schritte auszuführen, tun Sie das, bevor Sie sich wieder synchronisieren.

npx cap open ios

Abschließen Sie die Xcode-Schritte

In Xcode überprüfen Sie die App-Projekt- und Zielkonfiguration:

Bestätigen Sie

App-Erweiterungen, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks CapApp-SPM wird als lokale Abhängigkeit hinzugefügt.
Bestätigen Sie, dass die Zielanwendung auf die generierten Paketprodukte verlinkt ist.
Fügen Sie die generierten debug.xcconfig zur Projekt-Konfiguration hinzu, wenn der Assistent danach fragt.
Lösen Sie alle Paketwarnungen in Xcode.
Bauen Sie die App einmal von Xcode aus.

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

Synchronisieren und erneut bauen

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

npx cap sync ios

Bauen Sie dann erneut von Xcode aus. Behandeln Sie die Migration nicht als abgeschlossen, bis eine saubere Build von Xcode funktioniert, da die Freigabe-Zertifizierung, die Berechtigungen, die App-Erweiterungen und die Paketlösung dort validiert werden.

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

Alternative: Erstellen Sie iOS mit SPM neu

Wenn Ihr ios/ Ordner sich dem Standard-Capacitor-Template annähert, kann es schneller sein, ihn mit SPM neu zu erstellen, anstatt ihn in-place zu migrieren.

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

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

Rufen Sie dann Ihre app-spezifischen native Dateien und Einstellungen wieder her. Diese Methode gibt Ihnen einen sauberen SPM-Projekt, aber es ist einfacher, bei nicht-inventarisierten Xcode-Änderungen Ihre Anwendungsdaten zu verlieren.

Für neue Capacitor-Anwendungen 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

Löschen Sie CocoaPods-Überreste

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

Entfernen Sie Schritte wie:

pod install

Entfernen Sie auch Caches, die nur für CocoaPods existierten:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods Specs 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 noch immer 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.

Problembehandlung

Kontext: Unterstützung / Premium-Unterstützung-Seite oder Fußzeile-Unterstützungsabschnitt. Rolle: Abschnitt- oder Seiteüberschrift. Gesehen in: Seite support-policy.astro. Nachrichtenschlüssel `support_policy_troubleshooting_title` (Unterstützungspolitik-Problembehandlungstitel).

Der Assistent warnt vor einer inkompatiblen Abhängigkeit

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

Xcode kann Pakete nicht auflösen CapApp-SPM Richten Sie die Paket-Caches in Xcode neu, überprüfen Sie, ob npx cap sync ios ist als lokales Paket vorhanden und führen Sie erneut aus.

Die App baut lokal, aber CI fehlschlägt

Suchen Sie nach alten CocoaPods-Ansätzen: pod install, Pods/ caches, Podfile.lock Cache-Schlüssel oder Build-Befehle, die auf einen gelöschten .xcworkspace.

Signierung oder Berechtigungen geändert

Vergleichen Sie das migrierte Xcode-Ziel mit dem Projekt vor der Migration. Setzen Sie den Bundle-Identifier, Team, Provisioning-Profil, Entitlements-Datei, Fähigkeiten und Erweiterungseinstellungen wieder her.

Migration-Checkliste

Bevor die Migration:

Erstellen Sie einen Zweig.
Bestätigen Sie, dass die aktuelle iOS-App baut.
Kommentieren Sie den Arbeitszustand.
Erstellen Sie eine Liste der benutzerdefinierten nativen Dateien und Signierungseinstellungen.
Aktualisieren Sie native Abhängigkeiten, die bereits neuerere SPM-kompatible Versionen haben.

Während der Migration:

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

Nach der Migration:

Bauen Sie die App in Xcode.
Test 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 zur Handhabung der Migration verwenden, beginnen Sie mit Capgo Fähigkeiten anstatt einem leeren Prompt. Die nützlichsten Fähigkeiten für diese Arbeit sind:

capacitor-best-practices die App-Struktur vor dem Ändern zu überprüfen. ios/.
cocoapods-to-spm die SPM-Migration und Xcode-Folge-Schritte zu planen.
capacitor-ci-cd CocoaPods-Ansätze aus Build-Pipelines zu entfernen.
debugging-capacitor und ios-android-logs Migrieren Sie Ihr __CAPGO_KEEP_0__-Projekt zur 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

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

Zusammenfassung

Die Migration eines Capacitor-Projekts zur 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-assistantFinishen Sie die manuellen Xcode-Schritte, synchronisieren Sie sich erneut und entfernen Sie CocoaPods nur aus dem CI, nachdem das Projekt gebaut wurde.

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

Wie Sie Ihre Capacitor-Anwendung auf Swift Package Manager migrieren