Come Migliare un'app Capacitor a Manager dei Pacchetti Swift

Capacitor 8 crea nuovi progetti iOS con Swift Package Manager (SPM) di default. Gli app esistenti che ancora utilizzano CocoaPods possono migrare, ma il percorso più sicuro dipende da quanto la tua app ha personalizzato iOS nativo.

Questa guida passa attraverso le modifiche, cosa salvare e le due opzioni di migrazione pratiche: utilizzare l'assistente di migrazione Capacitor o ricostruire il progetto iOS con SPM.

Perché migrare ora

CocoaPods si sta spostando verso un tronco di sola lettura. Il piano attuale è che il tronco di CocoaPods smetta di accettare nuove podspecs il 2 dicembre 2026. Le costruzioni esistenti dovrebbero continuare a funzionare, ma le nuove rilasci e gli aggiornamenti di dipendenza che dipendono dal tronco non saranno pubblicati lì dopo il passaggio.

SPM è anche la direzione in cui Capacitor sta muovendosi. Capacitor ha supportato la scelta tra CocoaPods o SPM dal Capacitor 6, e Capacitor 8 crea ora progetti iOS SPM come modello di default.

Cosa cambia in un progetto Capacitor SPM

La migrazione da CocoaPods a SPM sostituisce il layer di dipendenza iOS. L'app web, il progetto Android e la maggior parte dei comandi di workflow Capacitor rimangono gli stessi.

CapApp-SPM sostituisce il Podfile

In un'app di CocoaPods, le dipendenze iOS sono connesse attraverso ios/App/Podfile, Podfile.lock, Pods/, e il file generato .xcworkspace.

In un'app SPM, Capacitor crea un pacchetto locale denominato CapApp-SPM. Questo pacchetto diventa il luogo centrale dove Capacitor riferisce le dipendenze native del tuo plugin iOS. Il Capacitor CLI si aggiorna CapApp-SPM quando sincronizzi i plugin, quindi trattalo come output generato e evita di modificarlo a mano.

debug.xcconfig sostituisce la configurazione di Pods

L'assistente di migrazione crea anche un file generato debug.xcconfig. Questo file contiene impostazioni di compilazione che CocoaPods forniva precedentemente attraverso i suoi file xcconfig generati.

Dopo la migrazione, potresti dover aggiungere debug.xcconfig alla configurazione del progetto Xcode se l'assistente ti dice di farlo.

Ogni plugin deve supportare SPM

Non puoi mixare CocoaPods e SPM nello stesso progetto iOS Capacitor. Prima di migrare, controlla ogni Capacitor e plugin Cordova in package.json.

Se un plugin non supporta ancora SPM, aggiornalo, sostituiscilo o migra il plugin prima. I plugin Swift semplici possono spesso essere convertiti con Ionic’s capacitor-plugin-converter, ma i plugin con layout più complessi di Objective-C e Swift potrebbero richiedere lavoro manuale.

Cosa salvare per primo

Inizia da una branca Git pulita e commetta lo stato attuale prima di toccare il progetto iOS. Poi elenca i file nativi su cui il tuo app dipende.

File comuni da preservare da ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, se il tuo app ne ha uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, se utilizzi Firebase
Personalizzato .xcconfig file
Impostazioni di firma, identificatore bundle, ID team e impostazioni di provisioning

Preserva anche qualsiasi file Swift, Objective-C, framework, estensione o SDK che hai aggiunto al di fuori del modello standard Capacitor.

Opzione 1: Utilizza l'assistente di migrazione Capacitor

Utilizza questo percorso quando il progetto iOS ha modifiche native personalizzate che non vuoi perdere.

Esegui l'assistente dalla radice del tuo progetto Capacitor:

bunx cap spm-migration-assistant

L'assistente elimina l'infrastruttura CocoaPods, crea il pacchetto locale, genera riferimenti di pacchetto dai tuoi plugin installati e crea i file di configurazione SPM generati. CapApp-SPM Quando è finito, apri il progetto:

Segui quindi i passaggi manuali di Xcode stampati dall'assistente. In quasi tutti i progetti ciò significa:

bunx cap open ios

Aggiungi

come dipendenza di pacchetto locale. CapApp-SPM Aggiungi il
alla configurazione dell'app. debug.xcconfig Risolve eventuali avvisi sui plugin che non sono stati convertiti in SPM.
Costruisci l'applicazione da Xcode una volta prima di aggiornare CI.
Dopo che il progetto Xcode è stato costruito, sincronizza nuovamente:

Esegui l'assistente dalla radice del tuo progetto __CAPGO_KEEP_0__:

bunx cap sync ios

Opzione 2: Re-scaffold il progetto iOS con SPM

Usa questo percorso quando il tuo ios/ directory è vicino al modello di default Capacitor e puoi ripristinare in sicurezza i file personalizzati in seguito.

Prima di tutto assicurati che i file elencati nella sezione di backup siano commessi o copiati in un luogo sicuro. Poi rimuovi e ricrea il progetto iOS con SPM:

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

Ripristina i file nativi che il tuo app necessita, poi apri il progetto:

bunx cap open ios

Questo percorso è spesso più pulito di una migrazione in loco perché ti dà un modello Capacitor 8 iOS fresco. Il trade-off è che devi applicare con cura la firma, le autorizzazioni, i file Firebase, le modifiche alle fonti native e qualsiasi impostazione Xcode personalizzata.

Nuove Capacitor app

Per un'app nuova, Capacitor 8 utilizza SPM per impostazione predefinita quando si aggiunge iOS:

bunx cap add ios

Se hai bisogno di essere esplicito, puoi ancora passare l'opzione del gestore di pacchetti:

bunx cap add ios --packagemanager SPM

Aggiorna CI dopo la migrazione

Una volta che l'app si costruisce localmente, aggiorna CI/CD in modo che non assuma più CocoaPods.

Elimina i passaggi che eseguono:

pod install

Rimuovi anche le cache per:

ios/App/Pods
ios/App/Podfile.lock
I repository di specie CocoaPods, se il tuo workflow le ha cache solo per questa app

Mantieni i passaggi di sincronizzazione regolari per il tuo build web e Capacitor. Un lavoro iOS tipico dovrebbe installare le dipendenze JavaScript, costruire gli asset web, sincronizzare Capacitor, e poi costruire con Xcode:

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

Elenco di controllo di migrazione

Prima della migrazione:

Crea una nuova branca Git.
Commetti l'applicazione di lavoro corrente.
Verifica che ogni plugin installato supporti SPM.
Ricorda i file e le impostazioni di firma iOS personalizzati.
Conferma che l'applicazione si costruisce prima della migrazione.

Durante la migrazione:

Esegui bunx cap spm-migration-assistant o riscavare la struttura ios/.
Aggiungi CapApp-SPM Aggiungi in Xcode se necessario.
Aggiungi debug.xcconfig Aggiungi in Xcode se necessario.
Ripristina file nativi specifici dell'applicazione.
Esegui bunx cap sync ios.

Dopo la migrazione:

Costruisci e esegui l'applicazione in Xcode.
Elimina file CocoaPods lasciati.
Elimina pod install dalla CI.
Verifica che la firma di rilascio funzioni ancora.
Esegui l'applicazione su almeno un simulatore e un dispositivo reale prima di distribuirla.

Risoluzione dei problemi

Se Xcode non riesce a risolvere i pacchetti, resettare le cache dei pacchetti da Xcode e riprovare. bunx cap sync ios Se la migrazione fallisce a causa di un plugin, controlla se il plugin ha una versione più recente con supporto per SPM. Per i plugin che gestisci, migra il pacchetto del plugin per primo e poi torna alla migrazione dell'app.

Quando l'app si costruisce localmente ma fallisce in CI, controlla per vecchie assunzioni di CocoaPods. Le cause comuni sono un percorso di costruzione forzato, un comando vecchio o caching da costruzioni precedenti.

Conclusione .xcworkspace Migrare un'app __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione delle dipendenze iOS. pod install Verify release signing still works. Pods/ Run the app on at least one simulator and one real device before shipping.

Troubleshooting

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM gestisce le riferimenti alle dipendenze, debug.xcconfig rappresenta la configurazione di costruzione CocoaPods generata e il CI non ha più bisogno di pod install.

Per i progetti iOS personalizzati, inizia con bunx cap spm-migration-assistant. Per i progetti vicini al modello di default, una ristrutturazione SPM pulita è spesso più veloce e facile da comprendere.

Risorse

Continua da Come migrare un'app Capacitor a Swift Package Manager

Se stai utilizzando Come migrare un'app Capacitor a Swift Package Manager per pianificare la migrazione e le operazioni aziendali, connettilo con Capgo Azienda per il workflow del prodotto in Capgo Azienda Alternative per plugin aziendale di Ionic per il workflow del prodotto in Alternative per plugin aziendale di Ionic Capgo Alternative per il workflow del prodotto in Capgo Alternative Capgo Consulenza per il workflow del prodotto in Capgo Consulenza, e Capgo Supporto Premium per il workflow del prodotto in Capgo Supporto Premium