Come migrare il tuo Capacitor app a Swift Package Manager

Manager dei Pacchetti Swift è la direzione predefinita per i progetti iOS Capacitor. 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 è per le squadre 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 CI dopo che l'app è stata costruita.

Cosa cambia nell'app

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

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

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named CapApp-SPM e lo utilizza per connettere il target dell'applicazione con Capacitor e le dipendenze native installate.

Il build web funziona sempre nello stesso modo. Esegui ancora un build web, sincronizza Capacitor, apri Xcode e archivia l'applicazione. 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'applicazione corrente si compili 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.

Successivamente, esamina cosa il tuo app ha personalizzato sotto ios/App/Il file e le impostazioni comuni da preservare includono:

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

Controlla anche le tue dipendenze Capacitor e Cordova installate. Una migrazione SPM dell'app può essere bloccata da una dipendenza nativa senza 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

Eseguilo 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 per il progetto iOS. CapApp-SPM Dopo che si è concluso, apri il progetto iOS:

Leggi l'output dell'assistente prima di chiudere il terminale. Se ti chiede di completare passaggi manuali in Xcode, esegui quei passaggi prima di sincronizzare nuovamente.

npx cap open ios

Completa i passaggi di Xcode

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

Conferma

Assicurati di aver completato tutti i passaggi necessari prima di procedere con la migrazione. CapApp-SPM è aggiunto come dipendenza di pacchetto locale.
Conferma che i collegamenti di destinazione dell'app puntano ai prodotti di pacchetto generati.
Aggiungi il generato debug.xcconfig a la configurazione del progetto se l'assistente 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 Pacchetti, quindi risolvi i pacchetti nuovamente.

Sincronizza e costruisci nuovamente

Dopo che Xcode è configurato, torna al terminale e sincronizza Capacitor:

npx cap sync ios

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

If l'applicazione utilizza le notifiche push, i domini associati, i modi di background, i gruppi di app, Firebase o qualsiasi configurazione nativa SDK, esegui quei flussi su un simulatore o dispositivo dopo che il build 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 fatto un backup di ogni file e impostazione nativa che ti servono:

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

Poi ripristina i file e le impostazioni nativi specifici 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 le nuove Capacitor applicazioni, Capacitor 8 crea progetti iOS con SPM di default:

npx cap add ios

Puoi ancora essere esplicito:

npx cap add ios --packagemanager SPM

Pulisci i residui di CocoaPods

Dopo che l'app SPM è stata costruita, elimina le assunzioni residue di CocoaPods dai script locali e dalla CI.

Elimina passaggi come:

pod install

Elimina anche le cache che esistevano solo per CocoaPods:

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

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

npm ci
npm run build
npx cap sync ios

Se il tuo CI ancora costruisce App.xcworkspace, aggiornalo al percorso del progetto o del workspace che esiste dopo la migrazione. Non tenere i percorsi CocoaPods obsoleti 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)

L'assistente avverte di un'interdipendenza incompatibile

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

Xcode non risolve i pacchetti CapApp-SPM Ripristina le cache dei pacchetti in Xcode, controlla che npx cap sync ios è presente come pacchetto locale, e esegui nuovamente

L'applicazione si costruisce localmente ma il CI fallisce

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.

Le firme o le autorizzazioni sono state modificate

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

Elenco di migrazione

Prima della migrazione:

Crea una branch.
Conferma che l'applicazione iOS corrente si costruisce.
Comita lo stato di lavoro.
Inventario file nativi personalizzati e impostazioni di firma.
Aggiorna le dipendenze native che già dispongono di rilasci più recenti compatibili con SPM.

Durante la migrazione:

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

Dopo la migrazione:

Costruisci l'applicazione da Xcode.
Testare le capacità native su un simulatore o dispositivo.
Eliminare le istruzioni di CocoaPods dal CI.
Eliminare i cache di CocoaPods esclusivi.
Verificare la firma di archiviazione e rilascio.

Utilizzare Capgo Skills per la migrazione.

Se utilizzi agenti AI per gestire la migrazione, inizia da __CAPGO_KEEP_0__ Skills. Capgo Skills per esaminare la struttura dell'app prima di apportare modifiche.

capacitor-best-practices per pianificare la migrazione SPM e i passaggi successivi di Xcode. ios/.
cocoapods-to-spm per eliminare le assunzioni di CocoaPods dai flussi di build.
capacitor-ci-cd e
debugging-capacitor e ios-android-logs Migrare le problematiche di dispositivo solo dopo la migrazione.

Utilizzarli prima di modificare il progetto iOS in modo che l'agente esamini i 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 per iOS. La via più sicura è iniziare da una branch pulita, eseguire npx cap spm-migration-assistantconcludere i passaggi manuali di Xcode, sincronizzare nuovamente e rimuovere CocoaPods dal CI solo dopo che l'app è stata costruita.

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

Come migrare il tuo app Capacitor a Manager dei Pacchetti Swift