Come migrare un'app Capacitor a Swift Package Manager

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 l'iOS nativo.

Questa guida guida attraverso le modifiche, cosa salvare e le due opzioni di migrazione pratiche: utilizzare l'Capacitor assistente di migrazione 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 smetterà di accettare nuove podspecs il 2 dicembre 2026. Le costruzioni esistenti dovrebbero continuare a funzionare, ma le nuove rilasci e gli aggiornamenti delle dipendenze che dipendono dal tronco non saranno pubblicati lì dopo lo switch.

SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.

What changes in a Capacitor SPM project

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 __CAPGO_KEEP_0__ rimangono gli stessi.

CapApp-SPM sostituisce il Podfile ios/App/Podfile, Podfile.lock, Pods/In un'app di CocoaPods, le dipendenze iOS sono connesse attraverso il file Podfile e le dipendenze sono gestite da CocoaPods. In un progetto SPM, le dipendenze sono gestite direttamente dal file Package.swift e le dipendenze sono specificate all'interno del file stesso. .xcworkspace.

In un'app SPM, Capacitor crea un pacchetto locale denominato 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, __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ aggiorna

Trattalo come output generato e evita di modificarlo a mano.

xcconfig di debug sostituisce la configurazione di Pods debug.xcconfigL'assistente di migrazione crea anche un file generato

Questo file contiene le impostazioni di costruzione che CocoaPods forniva attraverso i suoi file xcconfig generati. debug.xcconfig Dopo la migrazione, potresti dover aggiungere

a configurazione del progetto Xcode se l'assistente ti dice di farlo.

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

Non puoi mixare CocoaPods e SPM nello stesso progetto iOS __CAPGO_KEEP_0__. Prima di migrare, controlla ogni __CAPGO_KEEP_1__ e plugin Cordova in capacitor-plugin-converterSe un plugin non supporta ancora SPM, aggiornalo, sostituitelo o migra il plugin prima. I plugin Swift semplici possono spesso essere convertiti con Ionic's __CAPGO_KEEP_2__, 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. Quindi 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
File personalizzati .xcconfig File
Impostazioni di firma, identificatore di bundle, ID di team e impostazioni di profilo di provisioning

Preserva inoltre 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 tuo progetto iOS ha modifiche native personalizzate che non vuoi perdere.

Avvia 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:

Poi segui 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 il generato
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:

text

bunx cap sync ios

Opzione 2: Risciacquare nuovamente 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 stati commitati 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, 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 modello di 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 app

Per un'app nuova, 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

Rimuovi anche le cache per:

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

Mantieni i passaggi di sincronizzazione per il tuo build web regolare 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 branch Git.
Commetti l'applicazione di lavoro corrente.
Verifica che ogni plugin installato supporti SPM.
Registra i file iOS personalizzati e le impostazioni di firma.
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 specifici dell'applicazione.
Esegui bunx cap sync ios.

Dopo la migrazione:

Costruisci e esegui l'applicazione in Xcode.
Elimina file di CocoaPods lasciati.
Elimina pod install dal 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

context: 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). bunx cap sync ios Se Xcode non riesce a risolvere i pacchetti, resettare le cache dei pacchetti da Xcode e riprovare.

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 obsoleto o la cache da precedenti costruzioni. .xcworkspace Conclusioni pod install Migrare un'app __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione delle dipendenze iOS. Pods/ Verifica che la firma di rilascio funzioni ancora.

Esegui l'applicazione su almeno un simulatore e un dispositivo reale prima di distribuirla.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM assumerà le referenze alle dipendenze, debug.xcconfig sostituisce 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 alla plantilla di default, una pulizia SPM re-scaffold è 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 Enterprise di Ionic per il workflow del prodotto in Alternative per plugin Enterprise di Ionic Capgo Alternative per il workflow del prodotto in Capgo Alternative Capgo Consulting per il workflow del prodotto in Capgo Consulting, e Capgo Supporto Premium per il workflow del prodotto in Capgo Supporto Premium.