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 Ihre Release-Workflow von vorneherein neu aufzubauen.

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

Welche Änderungen 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

Ein SPM-basierte Capacitor-App verlagert die iOS-Abhängigkeitsverkabelung in Swift Package Manager. Während der Migration erstellt Capacitor ein lokales Paket mit dem Namen CapApp-SPM und verwendet es, um das Ziel des Apps 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 Capacitor, öffnen Xcode und archivieren die App. Der Hauptunterschied besteht darin, dass CocoaPods nicht mehr die iOS-Abhängigkeitsgraphik besitzt.

Bevor Sie migrieren

Beginnen Sie mit einer sauberen Zweig und stellen sicher, dass die aktuelle App vor dem Ändern der Abhängigkeitsmanager erstellt 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/Einige gemeinsame Dateien und Einstellungen sollten erhalten bleiben:

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
custom .xcconfig Dateien
Zertifikats- und Signierungseinstellungen, Bundle-Identifier, Team-ID und Berechtigungssätze
Anwendungs-Extensions, native Swift-Dateien, Objective-C-Dateien oder eingebettete Frameworks

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

Laufen Sie es vom Root Ihres Capacitor Projekts aus. Der Assistent entfernt die CocoaPods-Integration, erstellt die lokale CapApp-SPM Paket, generiert Paketverweise für installierte native Abhängigkeiten und fügt die benötigte Konfiguration hinzu, die von dem iOS-Projekt benötigt wird.

Nachdem es 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, manuelle Xcode-Schritte auszuführen, tun Sie das, bevor Sie erneut synchronisieren.

Fertigstellen Sie die Xcode-Schritte

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

Confirm CapApp-SPM wird als lokale Abhängigkeit hinzugefügt.
Bestätigen Sie, dass die Zielanwendung auf die generierten Paketprodukte verweist.
Fügen Sie die generierten debug.xcconfig zum Projektkonfiguration 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 bauen Sie erneut

Nachdem Xcode konfiguriert ist, kehren Sie zum Terminal 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 Flows auf einem Simulator oder Gerät aus, nachdem die Build erfolgreich ist.

Alternative: iOS mit SPM neu erstellen

Wenn Ihr ios/ Das Verzeichnis ist dem Standard Capacitor-Template nah, daher kann es schneller sein, es mit SPM neu zu erstellen als es in-place zu migrieren.

Nur verwenden Sie diesen Weg 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. Dieser Weg gibt Ihnen einen sauberen SPM-Projekt, aber es ist einfacher, benutzerdefinierte Xcode-Änderungen zu verlieren, wenn Sie sie nicht zuvor inventarisiert haben.

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

Überprüfen Sie die CocoaPods-Überreste

Nachdem das SPM-App erstellt wurde, entfernen Sie verbleibende 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-Spezifikations-Repositories
CI-Cache-Schlüssel basieren auf dem Podfile

Ein grundlegender CI-Flow nach der Migration sollte JavaScript-Abhängigkeiten installieren, die Web-Anwendung 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.

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.

Die App baut lokal, aber CI fehlschlägt

Suchen Sie nach alten CocoaPods-Annahmen: pod install, Pods/ Cache 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.

Migrationscheckliste

Bevor die Migration:

Erstellen Sie einen Zweig.
Bestätigen Sie die aktuellen iOS-App-Builds.
Kommentieren Sie den Arbeitszustand.
Verwalte benutzerdefinierte native Dateien und Signatur-Einstellungen.
Aktualisieren Sie native Abhängigkeiten, die bereits neuerere SPM-kompatible Releases haben.

Während der Migration:

Laufen npx cap spm-migration-assistant.
Öffnen Sie das Projekt mit npx cap open ios.
Hinzufügen CapApp-SPM im Xcode, wenn erforderlich.
Hinzufügen debug.xcconfig im Xcode, wenn erforderlich.
Warnungen für Pakete lösen.
Laufen npx cap sync ios.

Nach der Migration:

Die App aus Xcode erstellen.
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 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 der Änderung zu überprüfen. ios/.
cocoapods-to-spm die SPM-Migration und die Xcode-Folge-Schritte zu planen.
capacitor-ci-cd die CocoaPods-Ansätze aus den Build-Pipelines zu entfernen.
debugging-capacitor und ios-android-logs die Geräte-spezifischen Probleme nach der Migration zu untersuchen.

Migrieren Sie sie vor dem Ändern des iOS-Projekts, damit der Agent native Dateien, CI und Abhängigkeitskompatibilität überprüft, anstatt nur den Migration-Befehl auszuführen.

Zusammenfassung

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

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

Migration Ihres Capacitor-Apps auf Swift Package Manager