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

Diese Anleitung ist für App-Teams gedacht. Sie erklärt, wie Sie eine Capacitor-iOS-Anwendung von CocoaPods auf SPM migrieren, was der Migrations-Assistent ändert, was Sie noch in Xcode überprüfen müssen und wie Sie CI nach der App-Build sauber machen.

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-Anwendung verschiebt die iOS-Abhängigkeitskabelung in den Swift Package Manager. Während der Migration erstellt Capacitor eine lokale Paketdatei mit dem Namen CapApp-SPM und verwendet sie, um die Zielanwendung mit Capacitor und den installierten nativen Abhängigkeiten zu verbinden.

Die Web-Ausgabe funktioniert immer noch auf die gleiche Weise. Sie führen immer noch eine Web-Ausgabe aus, synchronisieren Capacitor, öffnen Xcode und archivieren die App. Die Hauptschwelle 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 dem Ändern der Abhängigkeitsmanager erfolgreich kompiliert wird:

git status
npm run build
npx cap sync ios

Dann committen Sie den Arbeitszustand. Die Migration berührt die generierten iOS-Projektdateien, daher ist es wichtig, einen sauberen Rollbackpunkt zu haben.

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

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
kostenlos .xcconfig Dateien
Signierungseinstellungen, Bundle-Bezeichner, Team-ID und Bereitstellungsprofile
App-Erweiterungen, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

Überprüfen Sie auch Ihre installierten Capacitor und Cordova-Abhängigkeiten. Eine App-basierte SPM-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 Migrationsassistenten

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

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:

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

npx cap open ios

Abschließen Sie die Xcode-Schritte

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

Bestätigen Sie

Confirm CapApp-SPM Wird als lokale Abhängigkeit des Pakets hinzugefügt.
Bestätigen Sie, dass die Zielanwendung auf die generierten Paketprodukte verlinkt ist.
Hinzufügen Sie die generierten debug.xcconfig zur Projekt-Konfiguration, wenn der Assistent danach fragt.
Beheben 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, lösen Sie die Pakete dann noch einmal.

Sync und bauen Sie noch einmal

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

npx cap sync ios

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

If die App Push-Benachrichtigungen verwendet, zugehörige Domains, Hintergrund-Modi, App-Gruppen, Firebase oder jede native SDK-Konfiguration, führen Sie diese Flows auf einem Simulator oder Gerät aus, nachdem die Erstellung erfolgreich war.

Alternative: Erstelle iOS mit SPM

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

Nur verwenden Sie diesen Weg nachdem Sie alle native Dateien und Signierungseinstellungen, die Sie benötigen, gespeichert 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, diese 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

Bereinigen Sie CocoaPods-Überreste

Nachdem das SPM-App 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 basieren 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-Flow immer noch baut App.xcworkspace, aktualisieren Sie ihn 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.

Fehlerbehebung

Der Assistent warnt vor einer inkompatiblen Abhängigkeit

Aktualisieren 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öschen Sie die Paket-Caches in Xcode, überprüfen Sie, ob CapApp-SPM als lokales Paket vorhanden ist und führen Sie npx cap sync ios erneut aus.

The App baut lokal, aber CI fehlschlägt

Suchen Sie nach alten CocoaPods-Anschlüssen: 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. Stellen Sie den Bundle-Identifier, Team, Provisioning-Profil, Berechtigungsdatei, Fähigkeiten und Erweiterungseinstellungen wieder her.

Migrationscheckliste

Vor der Migration:

Eine Zweig erstellen.
Bestätigen Sie, dass die aktuelle iOS-App lokal baut.
Die Arbeitsschritte committen.
Erstellen Sie eine Inventarliste für benutzerdefinierte native Dateien und Signierungseinstellungen.
Aktualisieren Sie native Abhängigkeiten, die bereits neuere 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 erforderlich.
Hinzufügen debug.xcconfig in Xcode erforderlich.
Beheben Sie Warnungen für Pakete.
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 verwenden, um die Migration zu handhaben, beginnen Sie mit Capgo Fähigkeiten anstatt eines leeren Vorgabeprotokolls. 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 die Xcode-Folge-Schritte zu planen.
capacitor-ci-cd CocoaPods-Vorannahmen aus Buildpipelines zu entfernen.
debugging-capacitor und ios-android-logs Nach der Migration Probleme, die nur auf Geräten auftreten, zu untersuchen.

Verwenden Sie sie, bevor Sie das 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 einer Capacitor-App zum Swift Package Manager ist hauptsächlich ein iOS-Abhängigkeitsmanagement-Wechsel. Der sichere Weg ist, von einem sauberen Branch aus zu beginnen, zu laufen npx cap spm-migration-assistant, die manuellen Xcode-Schritte zu beenden, noch einmal zu synchronisieren und CocoaPods aus dem CI nur nachdem die App gebaut ist, zu entfernen.

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

Wie Sie Ihre Capacitor-Anwendung auf Swift Package Manager migrieren