Wie migriert man eine Capacitor-App zum Swift Package Manager?

Capacitor 8 erstellt neue iOS-Projekte mit Swift Package Manager (SPM) standardmäßig. Bestehende Apps, die CocoaPods noch verwenden, können migriert werden, aber der sichere Weg hängt von der Menge an nativen iOS-Anpassungen in Ihrer App ab.

Dieses Leitfaden führt Sie durch die Änderungen, die Sicherung von Daten und die beiden praktischen Migrationen: die Verwendung des Capacitor-Migrationsassistenten oder die Neustrukturierung des iOS-Projekts mit SPM.

Warum jetzt migrieren?

CocoaPods ist auf dem Weg, eine lesende Trunk zu werden. Derzeit ist geplant, dass der CocoaPods-Trunk aufhört, neue Podspezifikationen zu akzeptieren, am Dezember 2, 2026. Bestehende Builds sollten weiterhin funktionieren, aber neue Releases und Abhängigkeitsupdates, die auf trunk basieren, werden dort nicht mehr veröffentlicht, nachdem der Wechsel erfolgt ist.

SPM ist auch die Richtung, in die Capacitor sich bewegt. Capacitor unterstützt seit Capacitor 6 die Auswahl zwischen CocoaPods und SPM und Capacitor 8 erstellt nun iOS-SPM-Projekte als Standardtemplate.

Welche Änderungen gibt es in einem Capacitor-SPM-Projekt?

Die Migration von CocoaPods zu SPM ersetzt die iOS-Abhängigkeitslayer. Die Web-App, das Android-Projekt und die meisten Capacitor-Workflow-Befehle bleiben unverändert.

CapApp-SPM ersetzt die Podfile

In einer CocoaPods-Anwendung werden iOS-Abhängigkeiten über ios/App/Podfile, Podfile.lock, Pods/und die generierte .xcworkspace.

In einer SPM-Anwendung erstellt Capacitor ein lokales Paket mit dem Namen CapApp-SPM. Dieses Paket wird zum zentralen Ort, an dem Capacitor Ihre native iOS-Plugin-Abhängigkeiten referenziert. Die Capacitor CLI-Updates CapApp-SPM werden, wenn Sie Plugins synchronisieren, daher behandeln Sie es als generiertes Ausgabe und vermeiden es, es manuell zu bearbeiten.

debug.xcconfig ersetzt die Pods-Konfiguration

Die Migrationshilfe erstellt auch einen generierten debug.xcconfigDieses Datei enthält die Build-Einstellungen, die CocoaPods früher über seine generierten xcconfig-Dateien bereitstellte.

Nach der Migration müssen Sie möglicherweise debug.xcconfig zum Xcode-Projekt-Konfiguration hinzufügen, wenn die Hilfsmittel Ihnen dazu auffordert.

Jeder Plugin muss SPM unterstützen

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

Wenn ein Plugin SPM noch nicht unterstützt, aktualisieren Sie es, ersetzen Sie es oder migrieren Sie das Plugin zuerst. Simple Swift-Plugins können oft mit Ionic's capacitor-plugin-converterkonvertiert werden, aber Plugins mit komplexeren Objective-C- und Swift-Anordnungen benötigen möglicherweise manuelle Arbeit.

Was zuerst sichern

Beginnen Sie mit einem sauberen Git-Zweig und speichern Sie Ihren aktuellen Zustand, bevor Sie das iOS-Projekt bearbeiten. Dann listen Sie die native Dateien auf, auf die Ihre App angewiesen ist.

Gemeinsame Dateien, die Sie aus ios/App/ einschließen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftWenn Ihr App eine hat
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistWenn Sie Firebase verwenden
Benutzerdefiniert .xcconfig Dateien
Signierungs-Einstellungen, Bundle-Identifier, Team-ID und Provisioning-Profile-Einstellungen

Behalten Sie auch alle native Swift, Objective-C, Framework, Erweiterung oder SDK-Dateien, die Sie außerhalb des Standard-Capacitor-Templates hinzugefügt haben.

Option 1: Nutzen Sie den Capacitor-Migration-Assistenten

Nutzen Sie diesen Pfad, wenn Ihr iOS-Projekt benutzerdefinierte native Änderungen enthält, die Sie nicht verlieren möchten.

Laufen Sie den Assistenten vom Root Ihres Capacitor-Projekts aus:

bunx cap spm-migration-assistant

Der Assistent entfernt die CocoaPods-Infrastruktur, erstellt die lokale Paketdatei, generiert Paketverweise aus Ihren installierten Plugins und erstellt die generierten SPM-Konfigurationsdateien. CapApp-SPM Wenn er fertig ist, öffnen Sie das Projekt:

Benutzerdefinierte

bunx cap open ios

Folgen Sie dann den manuellen Xcode-Schritten, die vom Assistenten ausgegeben werden. In den meisten Projekten bedeutet dies:

Hinzufügen CapApp-SPM als lokale Paketabhaengigkeit.
Fügen Sie die generierte debug.xcconfig zur Anwendungs-Konfiguration hinzu.
Beheben Sie alle Warnungen ueber Plugins, die nicht in SPM umgewandelt werden koennen.
Bauen Sie die Anwendung aus Xcode einmal vor der Aktualisierung von CI.

Nachdem das Xcode-Projekt gebaut wurde, synchronisieren Sie sich noch einmal:

bunx cap sync ios

Option 2: Erstellen Sie den iOS-Projekt mit SPM neu

Wenden Sie diese Methode an, wenn Ihr ios/ Verzeichnis sich nahe an der Standard-Capacitor-Vorlage befindet und Sie sicherstellen koennen, dass die benutzerdefinierten Dateien danach wiederhergestellt werden koennen.

Zuerst stellen Sie sicher, dass die in der Sicherung aufgeführten Dateien committet oder an einem sicheren Ort kopiert wurden. Dann entfernen und erzeugen Sie den iOS-Projekt mit SPM neu:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Die native Dateien, die Ihre App benötigt, wiederherstellen, und dann das Projekt öffnen:

bunx cap open ios

Dieser Weg ist oft sauberer als eine in-Place-Migration, da Sie ein frisches Capacitor 8 iOS-Vorlage erhalten. Der Handel ist, dass Sie die Signierung, die Berechtigungen, die Firebase-Dateien, die native Quellcode-Änderungen und alle benutzerdefinierten Xcode-Einstellungen sorgfältig wiederherstellen müssen.

Neue Capacitor Apps

Bei einer neuen App verwendet Capacitor 8 SPM standardmäßig, wenn Sie iOS hinzufügen:

bunx cap add ios

Wenn Sie explizit sein müssen, können Sie den Paket-Manager-Option immer noch übergeben:

bunx cap add ios --packagemanager SPM

Update CI nach der Migration

Einmal das App lokal gebaut hat, aktualisieren Sie CI/CD, damit es nicht mehr CocoaPods annehmen sollte.

Schritte entfernen, die laufen:

pod install

Entfernen Sie auch die Caches für:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods Specs-Repositories, wenn Ihr Workflow sie nur für diese App gecacht hat

Halten Sie Ihre reguläre Web-Build und Capacitor-Sync-Schritte bei. Ein typischer iOS-Job sollte JavaScript-Abhängigkeiten installieren, die Web-Ressourcen bauen, Capacitor synchronisieren und dann mit Xcode bauen:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Migrationscheckliste

Bevor die Migration:

Erstellen Sie einen neuen Git-Zweig.
Kommentieren Sie die aktuelle Arbeitsanwendung.
Überprüfen Sie, ob alle installierten Plugins SPM unterstützen.
Protokollieren Sie benutzerdefinierte iOS-Dateien und Signierungs-Einstellungen.
Bestätigen Sie, dass die Anwendung vor der Migration erfolgreich kompiliert wird.

Während der Migration:

Run bunx cap spm-migration-assistant oder rekonstruieren ios/.
Add CapApp-SPM im Xcode erforderlich.
Add debug.xcconfig im Xcode falls erforderlich.
App-spezifische native Dateien wiederherstellen.
Lauf bunx cap sync ios.

Nach der Migration:

Die App im Xcode erstellen und ausführen.
CocoaPods-Dateien entfernen.
Entferne pod install aus der CI.
Überprüfe, ob die Release-Zertifizierung noch funktioniert.
Die App auf mindestens einem Simulator und einem realen Gerät ausführen, bevor du sie verschickst.

Schwierigkeiten beheben

Kontext: Unterstützung / Premium-Unterstützung-Seite oder Fußzeile-Unterstützungsabschnitt. Rolle: Abschnitt oder Seiteüberschrift. Gesehen in: Seite support-policy.astro. Nachrichten Schlüssel `support_policy_troubleshooting_title` (Support Policy Troubleshooting Title). bunx cap sync ios wieder.

Wenn die App lokal gebaut wird, aber CI scheitert, überprüfen Sie alte CocoaPods-Anschauungen. Häufige Ursachen sind ein gezwungener Buildpfad, ein veraltetes Kommando oder Caching aus vorherigen Builds. .xcworkspace Fazit pod install Die Migration einer __CAPGO_KEEP_0__-App zum Swift Package Manager dreht sich hauptsächlich um die Ersetzung der iOS-Abhängigkeitsverkabelung. Pods/ übernimmt die Abhängigkeitsreferenzen,

ersetzt die generierte CocoaPods-Buildkonfiguration und CI benötigt

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Für Projekte, die sich der Standardvorlage nähern, ist oft eine saubere SPM-Wiederherstellung schneller und einfacher zu verstehen. debug.xcconfig Wenn die App lokal gebaut wird, aber CI scheitert, überprüfen Sie alte CocoaPods-Anschauungen. Häufige Ursachen sind ein gezwungener Buildpfad, ein veraltetes Kommando oder Caching aus vorherigen Builds. pod install.

Wenn die Migration aufgrund eines Plugins scheitert, überprüfen Sie, ob das Plugin eine neue Version mit SPM-Unterstützung hat. Für Plugins, die Sie unterhalten, migrieren Sie das Plugin-Paket zuerst und kehren dann zur App-Migration zurück. bunx cap spm-migration-assistantWenn die App lokal gebaut wird, aber CI scheitert, überprüfen Sie alte CocoaPods-Anschauungen. Häufige Ursachen sind ein gezwungener Buildpfad, ein veraltetes Kommando oder Caching aus vorherigen Builds.

Ressourcen

Fortsetzung von Wie Sie eine Capacitor-App auf den Swift Package Manager migrieren

Wenn Sie __CAPGO_KEEP_0__ verwenden Wie Sie eine Capacitor-App auf den Swift Package Manager migrieren um die Migration und die Unternehmensoperationen zu planen und zu verbinden, verbinden Sie es mit Capgo Enterprise for the product workflow in Capgo Enterprise, zur Produktworkflow in __CAPGO_KEEP_0__ Enterprise, und zur Produktworkflow in Ionic Enterprise Plugin Alternativen Capgo Alternativen zur Produktworkflow in Capgo Alternativen Capgo Consulting zur Produktworkflow in Capgo Consulting und Capgo Premium Support zur Produktworkflow in Capgo Premium Support.

Wie man eine Capacitor-App auf Swift Package Manager migriert