Come migrare il tuo Capacitor app a Swift Package Manager

Swift Package Manager è la direzione predefinita per Capacitor progetti iOS. Se il tuo app utilizza ancora CocoaPods, puoi migrare l'app stessa a SPM senza ricostruire il tuo progetto JavaScript code, il progetto Android o il flusso di rilascio da zero.

Questa guida è destinata alle squadre di sviluppo di app. Spiega come migrare un'app Capacitor iOS da CocoaPods a SPM, cosa cambia l'assistente di migrazione, cosa devi ancora controllare in Xcode e come pulire il CI dopo che l'app è stata costruita.

Cosa cambia nell'app

Un'app basata su CocoaPods Capacitor dipende da file come:

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

Un'app basata su SPM Capacitor sposta la gestione delle dipendenze iOS nel Swift Package Manager. Durante la migrazione, Capacitor crea un pacchetto locale denominato CapApp-SPM e lo utilizza per collegare il target dell'app con Capacitor e le dipendenze native installate.

Il build web funziona sempre nello stesso modo. Rilasci ancora un build web, sincronizza Capacitor, apri Xcode e archivia l'app. La principale differenza è che CocoaPods non gestisce più il grafo delle dipendenze iOS.

Prima di migrare

Inizia da una branch pulita e assicurati che l'app corrente si costruisca prima di modificare i gestori di dipendenze:

git status
npm run build
npx cap sync ios

Poi commetti lo stato di lavoro. La migrazione tocca i file di progetto iOS generati, quindi avere un punto di rollback pulito è importante.

Infine, esamina cosa il tuo app ha personalizzato sotto ios/App/File e impostazioni comuni da preservare includono:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftse presente
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistse utilizzi Firebase
personalizzato .xcconfig file
impostazioni di firma, identificatore bundle, ID team e profili di provisioning
estensioni dell'app, file Swift nativi, file Objective-C o framework incorporati

Controlla anche le tue dipendenze installate Capacitor e Cordova. Una migrazione SPM a livello di app può essere bloccata da una dipendenza nativa che non ha un percorso SPM compatibile. Aggiorna quei pacchetti prima di migrare quando possibile.

Usa l'assistente di migrazione

Per la maggior parte delle app esistenti, inizia con l'assistente di migrazione ufficiale Capacitor:

npx cap spm-migration-assistant

Eseguiscilo dalla radice del tuo progetto Capacitor. L'assistente elimina l'integrazione di CocoaPods, crea il pacchetto locale, genera riferimenti di pacchetto per le dipendenze native installate e aggiunge la configurazione generata necessaria al progetto iOS. CapApp-SPM Dopo che si è concluso, apri il progetto iOS:

se presente

npx cap open ios

Leggi l'output dell'assistente prima di chiudere il terminale. Se ti chiede di completare manualmente i passaggi di Xcode, esegui quelli prima di sincronizzare nuovamente.

Completa i passaggi di Xcode

In Xcode, controlla la configurazione del progetto e del target dell'app:

Conferma CapApp-SPM è aggiunto come dipendenza di pacchetto locale.
Conferma che il target dell'app collega i prodotti generati del pacchetto.
Aggiungi il pacchetto generato debug.xcconfig alla configurazione del progetto se l'assistente ti chiede di farlo.
Risolve eventuali avvisi di pacchetto in Xcode.
Costruisci l'app una volta da Xcode.

Se Xcode non riesce a risolvere i pacchetti, utilizza File > Pacchetti > Reset Cache dei Pacchettipoi, quindi risolvi i pacchetti di nuovo.

Risincronizza e costruisci nuovamente.

Dopo aver configurato Xcode, torna al terminale e sincronizza Capacitor:

npx cap sync ios

Poi costruisci nuovamente da Xcode. Non considerare la migrazione completa fino a quando un costruzione pulita funziona da Xcode, perché la firma di rilascio, le entità, le estensioni dell'app e la risoluzione dei pacchetti sono validate lì.

Se l'app utilizza le notifiche push, i domini associati, i modi di background, i gruppi dell'app, Firebase o qualsiasi configurazione nativa SDK, esegui quei flussi su un simulatore o dispositivo dopo che il costruzione ha avuto successo.

Alternativa: ricrea l'iOS con SPM

Se il tuo ios/ cartella è vicina al modello di default Capacitor, può essere più veloce ricrearla con SPM invece di migrare in loco.

Usa questa opzione solo dopo aver commesso o aver fatto un backup di ogni file e impostazione di firma nativa che ti serve:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Poi ripristina i file e le impostazioni native specifiche dell'app. Questa opzione ti dà un progetto SPM pulito, ma è più facile perdere le modifiche Xcode personalizzate se non hai inventariato le modifiche prima.

Per nuove Capacitor app, Capacitor 8 crea progetti iOS con SPM di default:

npx cap add ios

Puoi ancora essere esplicito:

npx cap add ios --packagemanager SPM

Elimina residui di CocoaPods

Dopo la compilazione dell'app SPM, elimina le assunzioni residue di CocoaPods dai script locali e da CI.

Elimina i passaggi come:

pod install

Elimina anche le cache che esistevano solo per CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repository dei spec di CocoaPods
Chiavi di cache di CI basate sul Podfile

Un flusso di CI base dopo la migrazione dovrebbe installare le dipendenze JavaScript, compilare l'app web, sincronizzare Capacitor, e compilare con Xcode:

npm ci
npm run build
npx cap sync ios

Se il tuo CI ancora compila App.xcworkspace, aggiorna il percorso del progetto o del workspace che esiste dopo la migrazione. Non tenere percorso di CocoaPods vecchio solo perché l'antico lavoro li utilizzava.

Risolvere i problemi

Contesto: Pagina/area: Supporto / sezione di supporto premium o sezione di supporto del footer. Ruolo: Intestazione di sezione o pagina. Visualizzato in: pagina support-policy.astro. Chiave di messaggio `support_policy_troubleshooting_title` (Titolo di supporto per la risoluzione dei problemi della politica di supporto).

L'assistente avverte di una dipendenza incompatibile con SPM. Aggiorna la dipendenza prima e esegui nuovamente l'assistente. Se non esiste una versione SPM compatibile, mantieni l'app su CocoaPods fino a quando non sostituisci quella dipendenza o il mantenitore aggiunge il supporto SPM.

Xcode non risolve i pacchetti

Riavvia le cache dei pacchetti in Xcode, assicurati che CapApp-SPM sia presente come pacchetto locale, e esegui npx cap sync ios di nuovo.

L'applicazione si costruisce localmente ma fallisce il CI

Cerca vecchie assunzioni di CocoaPods: pod install, Pods/ cache, Podfile.lock chiavi di cache o comandi di costruzione che puntano a un file eliminato .xcworkspace.

Cambiamenti di firma o autorizzazioni

Confronta il target Xcode migrato con il progetto pre-migrazione. Ripristina l'identificatore del bundle, l'equipe, il profilo di provisioning, il file delle autorizzazioni, le capacità e le impostazioni dell'estensione.

Elenco di migrazione

Prima della migrazione:

Creare una branca.
Confermare che l'app iOS corrente si compila.
Commitare lo stato di lavoro.
Elencare i file nativi personalizzati e le impostazioni di firma.
Aggiornare le dipendenze native che già dispongono di rilasci più recenti compatibili con SPM.

Durante la migrazione:

Eseguire npx cap spm-migration-assistant.
Apre il progetto con npx cap open ios.
Aggiungi CapApp-SPM in Xcode se richiesto.
Aggiungi debug.xcconfig in Xcode se richiesto.
Risolve le avvertenze sui pacchetti.
Esegui npx cap sync ios.

Dopo la migrazione:

Costruisci l'applicazione da Xcode.
Testa le capacità native su un simulatore o dispositivo.
Elimina le istruzioni di CocoaPods dal CI.
Elimina i cache di CocoaPods esclusivi.
Verifica la firma dell'archivio e della versione di rilascio.

Utilizza Capgo Skills per la migrazione.

Se utilizzi agenti AI per gestire la migrazione, inizia da Capgo Skills invece di una richiesta vuota. Le abilità più utili per questo lavoro sono:

capacitor-best-practices per esaminare la struttura dell'app prima di apportare modifiche ios/.
cocoapods-to-spm per pianificare i passaggi di migrazione SPM e di aggiornamento di Xcode.
capacitor-ci-cd per eliminare le assunzioni di CocoaPods dai flussi di build.
debugging-capacitor e ios-android-logs per investigare gli eventuali problemi di dispositivo dopo la migrazione.

Usali prima di modificare il progetto iOS in modo che l'agente esegua audit sui file nativi, CI e compatibilità delle dipendenze al posto di eseguire solo il comando di migrazione.

Conclusioni

Migrare un'app Capacitor a Swift Package Manager è principalmente un cambiamento di gestione delle dipendenze iOS. Il percorso più sicuro è iniziare da una branch pulita, eseguire npx cap spm-migration-assistantterminare i passaggi manuali di Xcode, sincronizzare nuovamente e rimuovere CocoaPods dal CI solo dopo che l'app è stata costruita.

Se il tuo progetto iOS è fortemente personalizzato, migra in loco. Se è vicino al modello di base Capacitor di Capgo, ricreare ios/ con npx cap add ios --packagemanager SPM può essere più pulito.

Come migrare il proprio Capacitor App al gestore di pacchetti Swift