Come Migliare un'app Capacitor a Gestore dei Pacchetti Swift

Capacitor 8 creates new iOS projects with Swift Package Manager (SPM) by default. Existing apps that still use CocoaPods can migrate too, but the safest path depends on how much native iOS customization your app has.

This guide walks through what changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with 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 2 dicembre 2026Le costruzioni esistenti dovrebbero continuare a funzionare, ma le nuove rilasci e gli aggiornamenti delle dipendenze che dipendono da trunk non saranno pubblicati lì dopo il passaggio.

SPM è anche la direzione in cui si sta muovendo Capacitor. Capacitor ha supportato la scelta tra CocoaPods o SPM dal Capacitor 6, e Capacitor 8 crea ora i 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 CocoaPods, le dipendenze iOS sono connesse tramite ios/App/Podfile, Podfile.lock, Pods/, e il file .xcworkspace.

In un'app SPM, Capacitor crea un pacchetto locale denominato CapApp-SPM. Questo pacchetto diventa il luogo centrale in cui Capacitor riferisce le dipendenze native iOS dei plugin. Le Capacitor CLI vengono aggiornate CapApp-SPM quando sincronizzi i plugin, quindi trattalo come output generato e evita di modificarlo a mano.

debug.xcconfig sostituisce la configurazione Pods

The assistente di migrazione crea anche un file generato debug.xcconfigQuesto file contiene le impostazioni di costruzione che CocoaPods utilizzava per fornire 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 è possibile miscelare CocoaPods e SPM nello stesso Capacitor progetto iOS. Prima di migrare, controlla ogni Capacitor e plugin Cordova in package.json.

Se un plugin non supporta ancora SPM, aggiornalo, sostituitelo o migra il plugin prima. capacitor-plugin-converterI plugin Swift semplici possono spesso essere convertiti con Ionic’s

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. ios/App/ I file comuni da preservare da "include":

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, se la tua app 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 di bundle, ID team e impostazioni di profilo di provisioning

Preserva anche eventuali file Swift nativi, Objective-C, framework, estensioni o SDK aggiunti al di fuori del modello standard Capacitor.

Opzione 1: Utilizza l'assistente di migrazione Capacitor

Utilizza questo percorso quando il tuo 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 di 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:

Opzione 2: Utilizza il percorso __CAPGO_KEEP_0__

bunx cap open ios

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

Aggiungi CapApp-SPM come dipendenza di pacchetto locale.
Aggiungi il generato debug.xcconfig alla configurazione dell'app.
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 di Xcode è stato costruito, sincronizza nuovamente:

bunx cap sync ios

Opzione 2: Riscava l'intero progetto iOS con SPM

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

Prima di tutto assicurati che i file elencati nella sezione di backup siano stati 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 richiede, quindi apri il progetto:

bunx cap open ios

Questa via è spesso più pulita di una migrazione in loco perché ti offre un Capacitor fresco 8 template per iOS. Il trade-off è che devi applicare con cura la firma, le autorizzazioni, i file Firebase, i cambiamenti di origine nativa e qualsiasi impostazione Xcode personalizzata.

Nuove Capacitor app

Per una nuova app, Capacitor 8 utilizza SPM di default 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

Elimina anche le cache per:

ios/App/Pods
ios/App/Podfile.lock
Ripostori dei spec CocoaPods, se il tuo workflow le ha cache solo per questa app

Mantieni i passaggi di costruzione web regolari e Capacitor sincronizza. 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 branch di Git.
Commetti l'applicazione di lavoro corrente.
Verifica che ogni plugin installato supporti SPM.
Ricorda i file iOS personalizzati e le impostazioni di firma.
Conferma che l'applicazione si compili prima della migrazione.

Durante la migrazione:

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

Dopo la migrazione:

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

Risolvere i problemi

Se Xcode non riesce a risolvere i pacchetti, resettare le cache dei pacchetti da Xcode e esegui bunx cap sync ios di nuovo.

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 le vecchie ipotesi di CocoaPods. Le cause comuni sono un percorso di costruzione forzato, un comando "stale", o la cache da costruzioni precedenti. .xcworkspace Conclusioni pod install Migrare un'app __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione di riferimento delle dipendenze iOS. Pods/ SPM si occupa delle riferenze alle dipendenze, sostituisce la configurazione di costruzione generata di CocoaPods e CI non ha più bisogno di

Per i progetti iOS personalizzati, inizia con

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Forced debug.xcconfig stale pod install.

caching bunx cap spm-migration-assistantfrom

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 Enterprise per il workflow del prodotto in Capgo Enterprise Alternative per plugin aziendali di Ionic Enterprise per il flusso di lavoro del prodotto in Alternatives di Ionic Enterprise Plugin Capgo Alternatives per il flusso di lavoro del prodotto in Capgo Alternatives, Capgo Consulting per il flusso di lavoro del prodotto in Capgo Consulting, e Capgo Supporto Premium per il flusso di lavoro del prodotto in Capgo Supporto Premium.