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 Migration-Assistent ändert, was Sie noch in Xcode überprüfen müssen und wie Sie CI nach der App-Build-Reinigung aufbereiten.

Was ändert sich 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

Ein SPM-basiertes Capacitor-App verschiebt die iOS-Abhängigkeitskabel in Swift Package Manager. Während der Migration erstellt Capacitor ein lokales Paket mit dem Namen CapApp-SPM und verwendet es, 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. Der Hauptunterschied besteht darin, dass CocoaPods die iOS-Abhängigkeitsgraphik nicht mehr besitzt.

Bevor Sie migrieren

Beginnen Sie mit einer sauberen Zweig und stellen 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/verändert hat. Gemeinsame Dateien und Einstellungen, die Sie aufbewahren 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
Signierungseinstellungen, Bundle-Identifikator, 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 keine SPM-kompatiblen Pfad hat. Aktualisieren Sie diese Pakete, wenn möglich, bevor Sie migrieren.

Verwenden Sie den Migration-Assistenten

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

npx cap spm-migration-assistant

Starten Sie es vom Root-Verzeichnis Ihres Capacitor-Projekts. 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 es Sie auffordert, manuelle Xcode-Schritte abzuschließen, tun Sie das, bevor Sie sich wieder synchronisieren.

npx cap open ios

Abschließen Sie die Xcode-Schritte

In Xcode überprüfen Sie die Anwendung-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 verweist.
Die generierten debug.xcconfig fügen Sie die generierten
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 Dann lösen Sie die Pakete erneut.Synchronisieren und bauen Sie erneut

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

After Xcode is configured, return to the terminal and sync Capacitor:

npx cap sync ios

Wenn Xcode die Pakete nicht lösen kann, verwenden Sie "File > Packages > Reset Package Caches"

If die App Push-Benachrichtigungen verwendet, zugehörige Domains, Hintergrundmodi, 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 der Standard-Capacitor-Vorlage 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 nach dem Commit oder dem Backup aller native Dateien und Signierungseinstellungen, die Sie benötigen:

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 alle benutzerdefinierten Xcode-Änderungen vorher 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-Fluss 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.

Fehlersuche

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 fehlt

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. Richten Sie die Bundle-Identifier, Team, Provisioning-Profil, Berechtigungsdatei, Fähigkeiten und Erweiterungseinstellungen wieder ein.

Migrationscheckliste

Vor der Migration:

Erstellen Sie eine Zweig.
Bestätigen Sie, dass die aktuelle iOS-App gebaut wird.
Kommentieren Sie den Arbeitszustand.
Erstellen Sie eine Liste der benutzerdefinierten nativen Dateien und Signierungseinstellungen.
Aktualisieren Sie native Abhängigkeiten, die bereits neuerere SPM-kompatible Releases 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.
Auflösen von Paketwarnungen.
Ausführen npx cap sync ios.

Nach der Migration:

Die App aus Xcode erstellen.
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 einer leeren Anfrage. 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 sind Geräte-spezifische Probleme 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 eines Capacitor-Apps zu Swift Package Manager ist hauptsächlich ein iOS-Abhängigkeits-Verwaltungswandel. Der sichere Weg ist, von einem sauberen Branch aus zu beginnen, 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 der Standard Capacitor-Template nähert, kann die Wiederherstellung ios/ mit npx cap add ios --packagemanager SPM kann sauberer sein.

Wie Sie Ihre Capacitor-Anwendung auf Swift Package Manager migrieren