Come migrare un'app Capacitor a Swift Package Manager

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

Questa guida guida 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 2026Costruzioni esistenti dovrebbero continuare a funzionare, ma le nuove rilascio e gli aggiornamenti di dipendenza che dipendono da trunk non saranno pubblicati lì dopo il passaggio.

SPM è anche la direzione verso 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 SPM di Capacitor

Migrare 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/, and the generated .xcworkspace.

In un'app SPM, Capacitor crea un pacchetto locale chiamato CapApp-SPMQuesto pacchetto diventa il luogo centrale dove 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

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

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

Ogni plugin deve supportare SPM

Non è possibile combinare CocoaPods e SPM nello stesso progetto iOS Capacitor. Prima di migrare, controlla ogni Capacitor e plugin Cordova. package.json.

If a plugin does not support SPM yet, update it, replace it, or migrate the plugin first. Simple Swift plugins can often be converted with Ionic’s capacitor-plugin-converterma i plugin con layout di Objective-C e Swift più complessi potrebbero richiedere lavoro manuale.

Cosa salvare per primo

Start from a clean git branch and commit your current state before touching the iOS project. Then list the native files your app depends on.

File comuni da preservare ios/App/ include:

• App/Info.plist
• App/AppDelegate.swift
• App/SceneDelegate.swiftincludono: , 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 eventuali file nativi Swift, Objective-C, framework, estensioni o SDK aggiunti al di fuori del modello standard Capacitor.

Opzione 1: Utilizza l'assistente di migrazione Capacitor

Utilizzare 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 la versione locale CapApp-SPM pacchetto, genera riferimenti di pacchetto dai tuoi plugin installati, e crea i file di configurazione SPM generati.

Apri il progetto quando è pronto.

bunx cap open ios

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

1. Aggiungi CapApp-SPM come dipendenza di pacchetto locale.
2. Aggiungi il generato debug.xcconfig al configurazione dell'applicazione.
3. Risolve eventuali avvisi sui plugin che non sono stati convertiti in SPM.
4. Costruisci l'applicazione da Xcode una volta prima di aggiornare CI.

Dopo la compilazione del progetto Xcode, sincronizza nuovamente:

bunx cap sync ios

Opzione 2: Risciacqua il progetto iOS con SPM

Usa 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 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

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 riapplicare con cura la firma, le entità, i file Firebase, le modifiche alle fonti native e qualsiasi impostazione Xcode personalizzata.

Nuovi 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 supponga più CocoaPods.

Elimina i passaggi che eseguono:

pod install

Elimina anche le cache per:

• ios/App/Pods
• ios/App/Podfile.lock
• Raccolta di spec repos di CocoaPods, se il tuo workflow li ha solo per questa app

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with Xcode:

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

Elenco di migrazione

Prima della migrazione:

• Crea una nuova branch di Git.
• Comita l'applicazione di lavoro corrente.
• Verifica che ogni plugin installato supporti SPM.
• Registra file e impostazioni di firma iOS personalizzati.
• Conferma che l'applicazione si costruisce prima della migrazione.

Durante la migrazione:

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

Una volta migrato:

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

Risolvere problemi

Se Xcode non riesce a risolvere i pacchetti, resettare 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 CI fallisce, controlla vecchie assunzioni di CocoaPods. Le cause più comuni sono una forzatura .xcworkspace percorso di costruzione, un file obsoleto pod install comando, o caching Pods/ dalle versioni precedenti.

Conclusion

Migrare un'app Capacitor a Swift Package Manager si concentra principalmente sulla sostituzione della gestione delle dipendenze iOS. CapApp-SPM assorbona le riferimenti alle dipendenze, debug.xcconfig rimpiazza la configurazione di costruzione CocoaPods generata, e il CI non ha più bisogno pod install.

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

Resources

• Capacitor Documentazione del gestore di pacchetti Swift
• Capacitor Guida aggiornamento 8
• piano di sola lettura trunk di CocoaPods
• capacitor-plugin-converter

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 flusso di lavoro del prodotto in Capgo Enterprise, Alternativi per Plugin Ionic Enterprise Alternative plugin Ionic Enterprise per il flusso di lavoro del prodotto Alternative di Capgo per il flusso di lavoro del prodotto in Capgo Alternatives Capgo consulenza 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.