Wie migrieren Sie Ihr Capacitor-Projekt zum Swift Package Manager?

Swift Package Manager ist die Standardrichtung für Capacitor-iOS-Projekte. Wenn Ihre Anwendung CocoaPods noch verwendet, können Sie die Anwendung selbst auf SPM migrieren, ohne Ihre JavaScript code-Anwendung, Ihr Android-Projekt oder Ihren Release-Workflow von vorne aufbauen zu müssen.

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

Welche Änderungen im App

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

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

Eine SPM-basierte Capacitor-Anwendung verlagert die iOS-Abhängigkeitsverkabelung in Swift Package Manager. Während der Migration erstellt Capacitor eine lokale Paketdatei namens CapApp-SPM und verwendet sie, 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 einer sauberen Zweig 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

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

Zuerst, überprüfen Sie, was Ihre App unter ios/App/. Gemeinsame Dateien und Einstellungen, die beibehalten werden 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
Benutzerdefinierte .xcconfig Dateien
Signierungs-Einstellungen, Bundle-Identifier, Team-ID und Bereitstellungsprofile
App-Erweiterungen, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

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

Nutzen Sie den Migrations-Assistenten

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

npx cap spm-migration-assistant

Führen Sie ihn vom Root Ihres Capacitor-Projekts aus aus. Der Assistent entfernt die CocoaPods-Integration, erstellt den lokalen CapApp-SPM generiert Paketverweise für installierte native Abhängigkeiten und fügt die generierte Konfiguration hinzu, die von dem iOS-Projekt benötigt wird.

Öffnen Sie nach Abschluss das iOS-Projekt:

npx cap open ios

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 erneut synchronisieren.

Abschließen Sie die Xcode-Schritte

In Xcode überprüfen Sie die Anwendungskonfiguration und das Ziel:

Bestätigen CapApp-SPM wird als lokale Paketabhängigkeit hinzugefügt.
Bestätigen Sie, dass die Anwendungskonfiguration auf die generierten Paketprodukte verlinkt ist.
Fügen Sie die generierte debug.xcconfig zur Projekt-Konfiguration hinzu, wenn der Assistent danach fragt.
Lösen Sie alle Paketwarnungen in Xcode.
Bauen Sie die Anwendung einmal von Xcode aus.

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

Synchronisieren und erneut bauen

Nachdem Xcode konfiguriert ist, kehren Sie zum Terminal 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, Hintergrund-Modi, 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 ist.

Alternative: iOS mit SPM neu erstellen

Wenn Ihr ios/ Ordner dem Standard-Capacitor-Template sehr ähnlich ist, 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:

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.

For neue Capacitor-Apps, Capacitor 8 erstellt iOS-Projekte mit SPM standardmäßig:

npx cap add ios

Sie können immer noch explizit sein:

npx cap add ios --packagemanager SPM

Räumen Sie CocoaPods-Überreste auf

Nachdem das SPM-App erstellt wurde, entfernen Sie veraltete 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. Halten Sie keine veralteten CocoaPods-Pfade auf, nur weil der alte Job sie verwendet hat.

Problembehandlung

Der Assistent warnt vor einer inkompatiblen Abhängigkeit

Update 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

Rufen Sie die Paket-Caches in Xcode zurück, überprüfen Sie, ob CapApp-SPM ist als lokales Paket vorhanden und führen Sie npx cap sync ios erneut aus.

Die App baut lokal, aber CI fehlt

Suchen Sie nach alten CocoaPods-Anschlüssen: pod install, Pods/ Kacheln Podfile.lock Cache-Schlüssel oder Build-Befehlen, die auf eine gelöschte .xcworkspace.

Signierung oder Berechtigungen wurden geändert

Vergleichen Sie das migrierte Xcode-Ziel mit dem Vor-Migrations-Projekt. Rufen Sie die Bundle-Identifier, Team, Provisioning-Profil, Berechtigungen-Datei, Fähigkeiten und Erweiterungseinstellungen zurück.

Migrationscheckliste

Vor der Migration:

Erstelle einen Zweig.
Bestätige, dass die aktuelle iOS-Anwendung kompiliert.
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.
Füge CapApp-SPM in Xcode, wenn erforderlich.
Hinzufügen debug.xcconfig in Xcode falls erforderlich.
Paketwarnungen lösen.
Ausführen npx cap sync ios.

Nach der Migration:

Die App aus Xcode erstellen.
NATIVE-Fähigkeiten 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 einer leeren Eingabeaufforderung. Die nützlichsten Fähigkeiten für diese Arbeit sind:

capacitor-best-practices um die App-Struktur vor dem Ändern zu überprüfen ios/.
cocoapods-to-spm um die Migration zum SPM und die Xcode-Schritte zu planen
capacitor-ci-cd um Annahmen von CocoaPods aus den Buildpipelines zu entfernen
debugging-capacitor und ios-android-logs um nach der Migration Geräte-spezifische Probleme zu untersuchen

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

Zusammenfassung

Die Migration einer Capacitor-App zum Swift Package Manager ist hauptsächlich ein Änderungsvorgang für die 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 zu beenden, noch einmal zu synchronisieren und CocoaPods aus dem CI nur nachdem die App gebaut ist zu entfernen

Wenn Ihr iOS-Projekt stark angepasst ist, migrieren Sie in Place. Wenn es sich nahe an der Standard- Capacitor-Vorlage befindet, sollten Sie es neu erstellen ios/ mit npx cap add ios --packagemanager SPM Kann dies sauberer sein.

Wie Sie Ihre Capacitor-App auf Swift Package Manager migrieren