Come migrare un'app Capacitor a Swift Package Manager

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 vie pratiche di migrazione: 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 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 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

La guida di migrazione dell'assistente crea anche un file generato debug.xcconfigQuesto file contiene le impostazioni di costruzione che CocoaPods forniva in precedenza 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 migra il plugin prima. 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 branca 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 context: Pagina/area: Sito web di marketing Capgo. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave di messaggio `custom` (Personalizzato).
file

Also preserve any native Swift, Objective-C, framework, extension, or SDK files you added outside the standard Capacitor template.

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

Opzione 1: Utilizzare l'assistente di migrazione __CAPGO_KEEP_0__

Run the assistant from the root of your Capacitor project:

bunx cap spm-migration-assistant

Eseguire l'assistente dalla radice del tuo progetto __CAPGO_KEEP_0__: CapApp-SPM L'assistente elimina l'infrastruttura di CocoaPods, crea il pacchetto locale, genera riferimenti di pacchetto dai plugin installati e crea i file di configurazione SPM generati.

Quando è finito, aprire il progetto:

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: Risciacqua 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 posto 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 nuovo Capacitor 8 template per iOS. Il trade-off è che devi applicare con cura la firma, le entità, i file Firebase, i cambiamenti di origine nativa 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

Elimina anche le cache per:

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

Conserva i passaggi di costruzione web e Capacitor regolari. 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 una nuova branch Git.
Commit l'applicazione in corso.
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 re-scaffold ios/.
Aggiungi CapApp-SPM in Xcode se necessario.
Aggiungi debug.xcconfig se richiesto in Xcode.
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 residui.
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 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 datato, o caching da costruzioni precedenti. .xcworkspace Conclusioni pod install Migrare un'app __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione di dipendenza iOS. Pods/ si occupa delle riferenze alle dipendenze, sostituisce la configurazione di costruzione generata da CocoaPods e CI non ha più bisogno

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 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. debug.xcconfig 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 datato, o caching da costruzioni precedenti. pod install.

Conclusioni bunx cap spm-migration-assistantMigrare un'app __CAPGO_KEEP_0__ a Swift Package Manager è principalmente questione di sostituire la configurazione di dipendenza iOS.

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 gli plugin 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.