Come migrare un'app Capacitor a Manager dei Pacchetti Swift

Capacitor 8 crea nuovi progetti iOS con Swift Package Manager (SPM) di default. Le app 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 ti guida 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 attuale di CocoaPods smetta di accettare nuove podspecs entro Dicembre 2, 2026. Le costruzioni esistenti dovrebbero continuare a funzionare, ma le nuove rilascio e le aggiornamenti delle dipendenze che dipendono da trunk non saranno pubblicati lì dopo il passaggio.

SPM è anche la direzione Capacitor sta prendendo. 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

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 di 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 generato .xcworkspace.

In un'app SPM, Capacitor crea un pacchetto locale chiamato CapApp-SPM. Questo 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 di Pods

L'assistente di migrazione crea anche un file generato debug.xcconfigQuesto file contiene le impostazioni di costruzione 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

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

Se un plugin non supporta ancora SPM, aggiornalo, sostituitelo o migralo per primo. I plugin Swift semplici possono spesso essere convertiti con Ionic's capacitor-plugin-converterma 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 corrente prima di toccare il progetto iOS. Poi elenca i file nativi su cui il tuo app dipende.

I file comuni da preservare da ios/App/ includono:

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

Preservate anche i file nativi Swift, Objective-C, framework, estensioni o SDK che avete aggiunto al di fuori del modello standard Capacitor.

Opzione 1: Utilizzare l'assistente di migrazione Capacitor

Utilizzare questo percorso quando il tuo progetto iOS ha modifiche native personalizzate che non desiderate 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 è finito, aprire il progetto:

Se il tuo app ha uno

bunx cap open ios

Segui poi i passaggi manuali di Xcode stampati dall'assistente. In quasi tutti i 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: Riscaglia 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 richiede, quindi apri il progetto:

bunx cap open ios

Questo percorso è spesso più pulito di una migrazione in loco perché ti offre 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 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
Spec repository di CocoaPods, se il tuo workflow le ha cache 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 controllo di migrazione

Prima della migrazione:

Creare una nuova branch Git.
Commit l'applicazione attuale.
Verificare che ogni plugin installato supporti SPM.
Registrare file e impostazioni di firma iOS personalizzati.
Confermare che l'applicazione si compili prima della migrazione.

Durante la migrazione:

Run bunx cap spm-migration-assistant o ristrutturare ios/.
Aggiungi CapApp-SPM in Xcode se necessario.
Aggiungi debug.xcconfig se richiesto in Xcode.
Ripristina file nativi app-specifici.
Esegui bunx cap sync ios.

Dopo la migrazione:

Esegui la compilazione e l'esecuzione dell'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 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 della politica di supporto). 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 assunzioni di CocoaPods. Le cause comuni sono un percorso di costruzione forzato, un comando obsoleto o una cache da precedenti costruzioni. .xcworkspace Conclusioni pod install Migrare un'app a __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione di dipendenze iOS. Pods/ si occupa delle riferenze alle dipendenze, sostituisce la configurazione di costruzione generata da CocoaPods e CI non ha più bisogno

Per progetti iOS personalizzati, inizia con

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced build path, a stale command, or caching from previous builds. debug.xcconfig If the migration fails because of a plugin, check whether the plugin has a newer release with SPM support. For plugins you maintain, migrate the plugin package first and then return to the app migration. pod install.

Conclusion bunx cap spm-migration-assistantMigrating a __CAPGO_KEEP_0__ app to Swift Package Manager is mostly about replacing the iOS dependency wiring.

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