Come Migliare un'app Capacitor a Gestore dei Pacchetti Swift

Capacitor 8 crea nuovi progetti iOS con Swift Package Manager (SPM) di default. Le 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 i due percorsi di migrazione pratici: 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 2026Le 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 si sta muovendo. 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

Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.

CapApp-SPM sostituisce il file Podfile

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

In an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates 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 le impostazioni di compilazione che CocoaPods forniva 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, verificare ogni Capacitor e plugin Cordova in package.json.

Se un plugin non supporta ancora SPM, aggiornalo, sostituitelo o migrare 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 branch 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 di bundle, ID team e impostazioni del profilo di provisioning

Preservate anche i file Swift nativi, Objective-C, framework, estensioni o SDK che avete aggiunto 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.

Eseguire 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 finisce, apri il progetto:

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

bunx cap open ios

Aggiungi

come dipendenza di pacchetto locale. CapApp-SPM Aggiungi i file generati
Aggiungi i file generati debug.xcconfig To la configurazione dell'applicazione.
Risolve eventuali avvertimenti 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:

bunx cap sync ios

Opzione 2: Re-scaffold il progetto iOS con SPM

Utilizza questo percorso quando il tuo ios/ directory è vicino alla cartella di default Capacitor del template e puoi sicuramente ripristinare 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 elimina 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, quindi apri il progetto:

bunx cap open ios

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

Nuove Capacitor applicazioni

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

bunx cap add ios

If necessario, puoi ancora passare l'opzione del gestore dei 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
I repository dei specs di CocoaPods, se il tuo workflow le ha cache solo per questa app

Mantieni i passaggi di sincronizzazione regolari per il 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:

Creare un nuovo ramo Git.
Commetti l'applicazione in corso di lavoro.
Verifica che ogni plugin installato supporti SPM.
Registra file iOS personalizzati e impostazioni di firma.
Conferma che l'app è stata costruita prima della migrazione.

Durante la migrazione:

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

Dopo la migrazione:

Costruisci e esegui l'applicazione in Xcode.
Elimina i file residui di CocoaPods.
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.

Risoluzione dei problemi

Se Xcode non riesce a risolvere i pacchetti, resetta 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'applicazione.

Quando l'applicazione si costruisce localmente ma CI fallisce, controlla le vecchie assunzioni di CocoaPods. Le cause comuni sono un percorso di costruzione forzato, una cache .xcworkspace vecchia pod install comando o caching Pods/ da costruzioni precedenti.

Conclusioni

Migrare un'app Capacitor a Swift Package Manager è principalmente questione di sostituire la configurazione delle dipendenze iOS. CapApp-SPM prende il controllo delle riferimenti alle dipendenze, debug.xcconfig sostituisce la configurazione di costruzione generata da CocoaPods, e il CI non ha più bisogno pod install.

Per i progetti iOS personalizzati, inizia con bunx cap spm-migration-assistant. Per i progetti vicini alla cartella di base, 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 Enterprise per il workflow del prodotto in Capgo Enterprise, Alternative per Plugin Aziendale di Ionic per il workflow del prodotto in Alternative per Plugin Aziendale di Ionic, Alternative per Capgo per il workflow del prodotto in Alternative per Capgo, Consulenza Capgo per il workflow del prodotto in Capgo Consulting, e Capgo Supporto Premium per il workflow del prodotto in Capgo Supporto Premium.

Come migrare un'app Capacitor a Swift Package Manager