Wie migriert man seine Capacitor App zu Swift Package Manager?

Swift Package Manager ist die Standardrichtung für Capacitor iOS-Projekte. Wenn Ihr App noch CocoaPods verwendet, können Sie die App selbst ohne das Neubauen Ihres JavaScript code, Android-Projekts oder Ihrer Veröffentlichungsworkflow von Grund auf neu migrieren.

Diese Anleitung ist für App-Teams gedacht. Sie erklärt, wie man eine Capacitor iOS-App von CocoaPods auf SPM migriert, was der Migration-Assistent ändert, was Sie noch in Xcode überprüfen müssen und wie Sie den CI nach der App-Buildung 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 ein lokales Paket mit dem Namen CapApp-SPM und verwendet es, um die App-Ziel mit Capacitor und 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 Capacitor, öffnen Xcode und archivieren die App. Die Hauptsache ist, dass CocoaPods nicht mehr die iOS-Abhängigkeitsgraphik besitzt.

Bevor Sie migrieren

Beginnen Sie mit einem sauberen Branch und stellen Sie sicher, dass die aktuelle App vor dem Ändern der Abhängigkeitsmanager erfolgreich gebaut 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/unter Verwendung von. Gemeinsame Dateien und Einstellungen, die Sie aufbewahren sollten, sind:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftWenn vorhanden
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistWenn Sie Firebase verwenden
Benutzerdefiniert .xcconfig Dateien
Zertifizierungseinstellungen, Bundle-Identifier, 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-Migration von SPM kann durch eine native Abhängigkeit blockiert werden, die keine SPM-kompatiblen Pfad hat. Aktualisieren Sie diese Pakete, wenn möglich, bevor Sie migrieren.

Nutzen Sie die Migrationsassistentin

Für die meisten bestehenden Apps beginnen Sie mit der offiziellen Capacitor Migrationsassistentin:

npx cap spm-migration-assistant

Starten Sie sie vom Root Ihres Capacitor-Projekts aus. Die Assistentin 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 sie fertig ist, öffnen Sie das iOS-Projekt:

Nachdem sie fertig ist, öffnen Sie das iOS-Projekt:

npx cap open ios

Bevor Sie das Terminal schließen, lesen Sie die Ausgabe des Assistenten. Wenn er Sie auffordert, die manuellen Xcode-Schritte abzuschließen, tun Sie das, bevor Sie erneut synchronisieren.

Abschließen Sie die Xcode-Schritte

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

Bestätigen CapApp-SPM ist als lokales Paketabhaengigkeit hinzugefuegt.
Bestätigen Sie, dass das Ziel des Anwendungsprojekts 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 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.

Synchronisieren und erneut bauen

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

npx cap sync ios

Dann bauen Sie erneut aus Xcode. Behandeln Sie die Migration nicht als abgeschlossen, bis ein sauberer Build aus Xcode funktioniert, da die Freigabe-Zertifizierung, die Berechtigungen, die App-Erweiterungen und die Paketauflö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 Flows auf einem Simulator oder Gerät aus, nachdem der Build erfolgreich war.

Alternative: iOS mit SPM neu erstellen

Wenn Ihr ios/ Ordner sich der Standard- Capacitor-Vorlage sehr nahe kommt, 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, die Sie benötigen, abgespeichert oder in die Versionierung aufgenommen 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. Diese Methode gibt Ihnen ein sauberes SPM-Projekt, aber es ist einfacher, bei nicht-inventarisierten Xcode-Änderungen die eigenen Anpassungen 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

Entfernen Sie CocoaPods-Reste

Entfernen Sie nach dem SPM-Anwendungsbuild die CocoaPods-Vorannahmen 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-Spezifikations-Repositories
CI-Cache-Schlüssel basierend auf dem Podfile

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

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. Behalten Sie keine veralteten CocoaPods-Pfade auf, nur weil der alte Job sie verwendet hat.

Problembehandlung

Der Assistent warnt vor einem 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 bei 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 ausführen npx cap sync ios wieder.

Die App baut sich lokal, aber CI fehlt

Suchen Sie nach alten CocoaPods-Voraussetzungen: pod install, Pods/ Caches, Podfile.lock Cache-Schlüssel oder Build-Befehle, die auf ein gelöschtes .xcworkspace.

Signieren oder Berechtigungen geändert

Vergleichen Sie das migrierte Xcode-Ziel mit dem Projekt vor der Migration. Rufen Sie die Bundle-Identifikator, Team, Bereitstellungsprofil, Berechtigungen-Datei, Funktionen und Erweiterungseinstellungen zurück.

Migration-Checkliste

Bevor die Migration:

Erstelle einen Zweig.
Bestätige, dass die aktuelle iOS-Anwendung kompiliert wird.
Komme zum aktuellen Zustand.
Erstelle eine Liste der benutzerdefinierten nativen Dateien und Signierungseinstellungen.
Aktualisiere nativ abhängige Bibliotheken, die bereits SPM-kompatible Versionen 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, wenn erforderlich.
Hinzufügen debug.xcconfig in Xcode, wenn erforderlich.
Paketwarnungen lösen.
Ausführen npx cap sync ios.

Nach der Migration:

Die App aus Xcode erstellen.
Native Funktionen auf einem Simulator oder Gerät testen.
CocoaPods-Befehle aus CI entfernen.
CocoaPods-spezifische Caches löschen.
Archiv- und Release-Zertifizierung überprüfen.

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 vor der Änderung die App-Struktur zu überprüfen ios/.
cocoapods-to-spm die Migration und die nachfolgenden Xcode-Schritte zu planen
capacitor-ci-cd CocoaPods-Vorannahmen aus den Buildpipelines zu entfernen
debugging-capacitor und ios-android-logs nach der Migration Geräte-spezifische Probleme 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

Migrating a Capacitor app to Swift Package Manager is mostly an iOS dependency-management change. The safest path is to start from a clean branch, run npx cap spm-migration-assistantWenn Ihr iOS-Projekt stark anpassungsfähig ist, migrieren Sie in Place. Wenn es sich dem Standard-Template von __CAPGO_KEEP_0__ annähert, kann die Wiederherstellung

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ sauberer sein. npx cap add ios --packagemanager SPM Abschluss

Wie Sie Ihre Capacitor-Anwendung auf Swift Package Manager migrieren