Come Migliare il tuo Capacitor app per il Manager dei Pacchetti Swift

Swift Package Manager è la direzione predefinita per i progetti Capacitor iOS. Se il tuo app utilizza ancora CocoaPods, puoi migrare l'app stessa su SPM senza ricostruire il tuo progetto JavaScript code, il progetto Android o il workflow di rilascio da zero.

Questa guida è per i team di app. Spiega come migrare un'app Capacitor iOS da CocoaPods a SPM, cosa cambia l'assistente di migrazione, cosa devi ancora controllare in Xcode e come pulire il CI dopo che l'app è stata costruita.

Cosa cambia nell'app

Un'app basata su CocoaPods Capacitor dipende da file come:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Un'app basata su SPM Capacitor sposta la gestione delle dipendenze iOS nel Swift Package Manager. Durante la migrazione, Capacitor crea un pacchetto locale denominato CapApp-SPM e lo utilizza per collegare il target dell'app con Capacitor e le dipendenze native installate.

Il build web funziona sempre nello stesso modo. Rilasci ancora un build web, sincronizza Capacitor, apri Xcode e archivia l'app. La principale differenza è che CocoaPods non gestisce più il grafo delle dipendenze iOS.

Prima di migrare

Avvia da una branca pulita e assicurati che l'app corrente si compili prima di modificare i gestori di dipendenza:

git status
npm run build
npx cap sync ios

Poi commetta lo stato di lavoro. La migrazione tocca i file del progetto iOS generati, quindi avere un punto di rollback pulito è importante.

Successivamente, revisiona cosa il tuo app ha personalizzato sotto ios/App/File e impostazioni comuni da preservare includono:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, se presente
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, se utilizzi Firebase
impostazioni di firma, identificatore di bundle, ID di team e profili di provisioning .xcconfig estensioni dell'app, file Swift nativi, file Objective-C o framework incorporati
Controlla anche le tue dipendenze __CAPGO_KEEP_0__ e Cordova installate. Una migrazione SPM dell'app può essere bloccata da una dipendenza nativa che non ha un percorso SPM compatibile. Aggiorna quei pacchetti prima di migrare quando possibile.
Usa l'assistente di migrazione

Also check your installed Capacitor and Cordova dependencies. An app-level SPM migration can be blocked by a native dependency that has no SPM-compatible path. Update those packages before migrating when possible.

Then commit the working state. The migration touches generated iOS project files, so having a clean rollback point matters. Next, review what your app has customized under Common files and settings to preserve include: custom files, if present, custom signing settings, bundle identifier, team ID, and provisioning profiles, app extensions, native Swift files, Objective-C files, or embedded frameworks. Also check your installed __CAPGO_KEEP_0__ and Cordova dependencies. An app-level SPM migration can be blocked by a native dependency that has no SPM-compatible path. Update those packages before migrating when possible. Use the migration assistant

For la maggior parte degli app esistenti, inizia con l'assistente di migrazione ufficiale Capacitor:

npx cap spm-migration-assistant

Eseguilo dalla radice del tuo progetto Capacitor. L'assistente elimina l'integrazione di CocoaPods, crea il pacchetto locale, genera riferimenti di pacchetto per le dipendenze native installate e aggiunge la configurazione generata necessaria al progetto iOS. CapApp-SPM Dopo che si è concluso, apri il progetto iOS:

Leggi l'output dell'assistente prima di chiudere il terminale. Se ti chiede di completare passaggi manuali in Xcode, esegui quei passaggi prima di sincronizzare nuovamente.

npx cap open ios

Completa i passaggi di Xcode

In Xcode, controlla la configurazione del progetto e del target dell'app:

Conferma

è aggiunto come dipendenza di pacchetto locale. CapApp-SPM Conferma che il target dell'app collega i prodotti generati del pacchetto.
Aggiungi il generato
alla configurazione del progetto se l'assistente ti chiede di farlo. debug.xcconfig Conferma
Risolve tutte le avvertenze sui pacchetti in Xcode.
Costruisci l'applicazione una volta da Xcode.

Se Xcode non riesce a risolvere i pacchetti, utilizza File > Pacchetti > Reset Cache dei Pacchetti, quindi risolvi i pacchetti nuovamente.

Sincronizza e costruisci nuovamente

Dopo che Xcode è configurato, torna al terminale e sincronizza Capacitor:

npx cap sync ios

Costruisci nuovamente da Xcode. Non considera la migrazione come completata fino a quando un costruzione pulita funziona da Xcode, poiché la firma di rilascio, le autorizzazioni, le estensioni dell'app, la risoluzione dei pacchetti sono validate lì.

Se l'app utilizza le notifiche push, i domini associati, i modi di background, i gruppi dell'app, Firebase o qualsiasi configurazione nativa SDK , esegui quei flussi su un simulatore o dispositivo dopo che il costruzione ha avuto successo.

Alternativa: ricrea iOS con SPM

Se il tuo ios/ cartella è vicina al modello di default Capacitor , può essere più veloce ricrearla con SPM invece di migrare in loco.

Usa solo questo percorso dopo aver effettuato il commit o aver fatto un backup di ogni file e impostazione nativa di cui hai bisogno:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Ripristina quindi i file e le impostazioni nativi specifici dell'app. Questo percorso ti da un progetto SPM pulito, ma è più facile perdere le modifiche Xcode personalizzate se non li hai inventariati prima.

Per nuove Capacitor app, Capacitor 8 crea progetti iOS con SPM di default:

npx cap add ios

Puoi comunque essere esplicito:

npx cap add ios --packagemanager SPM

Pulisci i residui di CocoaPods

Dopo che l'app SPM si è costruita, elimina le ipotesi residue di CocoaPods dai script locali e da CI.

Elimina passaggi come:

pod install

Elimina anche le cache che esistevano solo per CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Ripositorio dei spec di CocoaPods
Chiavi di cache CI basate sul Podfile

Un flusso di CI base dopo la migrazione dovrebbe installare le dipendenze JavaScript, costruire l'app web, sincronizzare Capacitor, e costruire con Xcode:

npm ci
npm run build
npx cap sync ios

Se il tuo CI continua a costruire App.xcworkspaceAggiornalo al percorso del progetto o dello spazio dei lavoro che esiste dopo la migrazione. Non mantenere percorso CocoaPods obsoleti solo perché l'antico lavoro li utilizzava.

Risolvere i problemi

La guida assistente avverte di una dipendenza incompatibile

Aggiorna la dipendenza per primo e esegui nuovamente la guida assistente. Se non esiste una versione SPM compatibile, mantieni l'applicazione su CocoaPods fino a quando non sostituisci quella dipendenza o il mantenitore aggiunge il supporto SPM.

Xcode non risolve i pacchetti

Ripristina le cache dei pacchetti in Xcode, assicurati che CapApp-SPM è presente come pacchetto locale, e esegui npx cap sync ios nuovamente.

L'applicazione si costruisce localmente ma fallisce in CI

Cerca vecchie assunzioni CocoaPods: pod install, Pods/ caché, Podfile.lock chiavi di cache o comandi di costruzione che puntano a un elemento eliminato .xcworkspace.

Modificati le firme o le autorizzazioni

Confronta il target Xcode migrato con il progetto pre-migrazione. Ripristina l'identificatore del pacchetto, l'equipe, il profilo di provisioning, il file delle autorizzazioni, le capacità e le impostazioni dell'estensione.

Elenco di controllo di migrazione

Prima della migrazione:

Creare una branca.
Conferma che l'app iOS corrente si compila.
Commetti lo stato di lavoro.
Elenco dei file nativi personalizzati e impostazioni di firma.
Aggiorna le dipendenze native che già hanno rilasci più recenti compatibili con SPM.

Durante la migrazione:

Esegui npx cap spm-migration-assistant.
Apre il progetto con npx cap open ios.
Aggiungi CapApp-SPM in Xcode se richiesto.
Aggiungi debug.xcconfig in Xcode se richiesto.
Risolve le avvertenze dei pacchetti.
Esegui npx cap sync ios.

Dopo la migrazione:

Costruisci l'applicazione da Xcode.
Testa le capacità native su un simulatore o dispositivo.
Elimina i comandi di CocoaPods dal CI.
Elimina le cache di CocoaPods esclusivamente.
Verifica la firma di archiviazione e rilascio.

Usa Capgo Skills per la migrazione

Se utilizzi agenti AI per gestire la migrazione, inizia da Capgo Skills invece di una richiesta vuota. Le competenze più utili per questo lavoro sono:

capacitor-best-practices per esaminare la struttura dell'applicazione prima di apportare modifiche ios/.
cocoapods-to-spm per pianificare i passaggi di migrazione dello SPM e delle fasi di follow-up di Xcode.
capacitor-ci-cd per eliminare le assunzioni di CocoaPods dai pipeline di costruzione.
debugging-capacitor e ios-android-logs per investigare problemi di dispositivo unici dopo la migrazione.

Usale prima di modificare il progetto iOS in modo che l'agente esamini file nativi, CI e compatibilità delle dipendenze al posto di eseguire solo il comando di migrazione.

Conclusioni

Migrare un'app Capacitor a Swift Package Manager è principalmente un cambiamento di gestione delle dipendenze iOS. Il percorso più sicuro è iniziare da una branch pulita, eseguire npx cap spm-migration-assistantCompleta i passaggi manuali in Xcode, sincronizza nuovamente e rimuovi CocoaPods dal CI solo dopo che l'app è stata costruita.

Se il tuo progetto iOS è pesantemente personalizzato, migra in loco. Se è vicino al modello di base Capacitor, ricreare ios/ con npx cap add ios --packagemanager SPM può essere più pulito.

Come migrare il tuo Capacitor App a Swift Package Manager