Capacitor 9 è disponibile sul next dist-tag mentre si avvia verso la disponibilità generale. Non devi aggiornare la tua app il giorno in cui arriva l'alpha, ma il guida ufficiale all'aggiornamento di Capacitor 9 e guida all'aggiornamento dei plugin già specificano i requisiti minimi della toolchain e le rimozioni di API da gestire in anticipo.
Questo articolo è una preparation : lavori che puoi eseguire su Capacitor 8 (o su una branch) in modo che il passaggio finale sia bunx cap migrate noioso invece che doloroso. Quando sei pronto per il cambio, segui le guide di Ionic collegate sopra, riga per riga.
Toolchain e requisiti minimi di piattaforma (app)
Pianifica CI, macchine locali e pipeline degli store in base a questi minimi:
| Area | Requisito Capacitor 9 |
|---|---|
| Node.js | 24+ (consigliata l'ultima LTS; npm 11 include Node 24) |
| Xcode | 27+ |
| Target di deployment iOS | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
Se stai ancora usando Capacitor 8.4 o versioni precedenti per iOS, hai anche bisogno del ciclo di vita UIScene lavora dall'aggiornamento Capacitor 8.5 prima di Cap 9 — Xcode 27 se lo aspetta. Le app già su 8.5 possono saltare quel passaggio extra.
Su iOS, Swift 6 (con Xcode 27) rifiuta @UIApplicationMain; quando fai l'upgrade, sostituiscilo con @main nella AppDelegate.swift come descritto nella guida ufficiale.
Cordova at app sync time (not a plugin prep step)
In Capacitor 9, il layer di compatibilità Cordova è integrato nella tua app solo quando cap sync rileva un plugin Cordova installato. Android rimuove i moduli Gradle extra quando non ce ne sono; iOS smette di aggiungere CapacitorCordova al Podfile o Package.swift quando non ce ne sono.
Si tratta di un app-level che cambia dopo l'upgrade. Finché sei ancora su Cap 8, non devi rimuovere Cordova dal template in via preventiva. Verifica però se ci sono plugin nativi code personalizzati (tuo o di un fork) che importano simboli Cordova senza un plugin Cordova reale nel progetto: quei riferimenti falliranno una volta applicata la configurazione opzionale di Cordova.
Android: gradle.properties e i default di AGP 9
L'AGP Upgrade Assistant spesso scrive gradle.properties flag per mantenere il comportamento di AGP 8 nei build. Le app Capacitor 9 dovrebbero rimuovere quelle voci invece di mantenerle: la maggior parte è deprecata in vista di AGP 10, e alcune rompono i build di Cap 9 (ad esempio, android.builtInKotlin=false disabilita il supporto Kotlin incluso in AGP 9, e android.sdk.defaultTargetSdkToCompileSdkIfUnset=false impedisce ad AGP di inferire targetSdkVersion).
Durante la migrazione, preparati anche a:
- Incrementa
variables.gradleminimi (compile/target SDK 37,minSdkVersion26, versioni AndroidX aggiornate — vedi la doc ufficiale). - Rimuovi l'esplicito
targetSdkVersionfrom the appbuild.gradlecosì AGP 9 può inferirlo dacompileSdkVersion. - Dichiara
variables.gradlei simboli in cima aapp/build.gradle(Gradle 9.6 depreca il lookup implicito dal progetto root). - Sostituisci i nomi dei file ProGuard predefiniti, migra
core-ktxaandroidx.core:core1.19.0+, abbandona l'uso del plugin Kotlin Gradle standalone e rimuovijcenter().
Puoi leggere i diff hunk nella Aggiornamento alla versione 9.0 sezione Android e applicare gli stessi cleanup su un branch prima di aggiornare le versioni di Capacitor.
CLI: cap run --url
Capacitor 9 unifica i flag live-reload host/port/https in un unico --url argomento. Invece di:
bunx cap run android -l --host 192.168.1.181 --port 5173
passa l'URL stampato dal tuo dev server:
bunx cap run android --url http://192.168.1.181:5173/
Aggiorna ora script e snippet del README per evitare che la memoria muscolare contrasti il nuovo CLI dopo l'upgrade.
Plugin ufficiali: criticità con push e splash
Due cambiamenti lato utente compaiono spesso nelle app in produzione:
Notifiche Push (iOS): Il deprecato alert di presentazione deprecata è stata rimossa. Usa banner e/o list nelle tue opzioni di presentazione.
Schermata di avvio (Android): Predefinito launchFadeOutDuration modifiche da 200 ms a 0. Se ti affidavi al fade per nascondere i glitch del primo render, imposta launchFadeOutDuration: 200 esplicitamente in capacitor.config finché non regoli la UI di avvio.
Scansiona le sezioni dei plugin nella guida di aggiornamento 9.0 per gli aggiornamenti di versione di AndroidX e Google Play Services legati ai plugin ufficiali che utilizzi.
Manutentori dei plugin: prepararsi su Cap 8 senza rompere Cap 8
Se pubblichi plugin Capacitor consumati su Capacitor 8 e vuoi code pronti per Cap 9, concentrati sulla rimozione dei API deprecati, non su modifiche di packaging esclusive per Cap-9.
Puoi farlo in sicurezza finché Cap 8 resta supportato:
- Sostituisci
@NativePlugincon@CapacitorPlugine migra le API legacy permission / activity-result ai@PermissionCallback/@ActivityCallbackpattern (vedi la tabella della guida al plugin 9.0 ). - Rimuovi
PluginCall.hasOption,Plugin.getConfigValue, vecchiCapConfigcostruttori e getter,PluginCall.save()/isSaved(), e altre rimozioni Java elencate in “Modifiche incompatibili in code”. - Su iOS, smetti di usare la
CAPBridgeclasse di compatibilità e gliCAPBridgeProtocolhelper deprecati; usaApplicationDelegateProxy, tipizzatoPluginCalle proprietà bridge dalla tabella di migrazione. - Esegui
bunx @capacitor/plugin-migration-v8-to-v9@latestsu un branch e mantieni solo le modifiche API che compilano ancora con le peer dependencies di Cap 8, finché non pubblichi una major per Cap 9.
Non rimuovere il Cordova prodotto SPM dal tuo plugin Package.swift finché supporti ancora Capacitor 8. I progetti Cap 8 si aspettano quella dipendenza quando il plugin è basato su SPM; rimuoverla troppo presto rompe i consumer ancora su 8. Tratta Cordova opzionale / rimozione della parte non condizionale Cordova prodotto come solo Capacitor 9 linea di release (o un semver major documentato esplicitamente come Cap 9+), dopo aver smesso di supportare Cap 8 — come descritto nella guida dei plugin, non come lavoro preparatorio sulla linea Cap 8.
La stessa regola vale per l'incremento capacitor-swift-pm a 9.0.0-alpha.x nella Package.swift: appartiene alla major di Cap 9, non a una release compatibile con Cap-8.
Capgo live updates e la build nativa per il Cap 9 store
Capgo distribuisce aggiornamenti web bundle via OTA; la shell nativa arriva comunque da App Store e Google Play. Quando sposti la tua app su Capacitor 9:
- Rilascia almeno una build per lo store compilato per 9 progetti nativi Capacitor (iOS e Android). Quel binario stabilisce la baseline nativa per i canali Capgo target.
- Solo dopo che quel build è nelle mani degli utenti dovresti affidarti a bundle OTA testati con il comportamento di WebView e plugin di Cap 9.
- Imposta i canali di produzione sulla
metadatastrategia e carica il bundle Cap 9 corrispondente su ogni canale con--auto-min-update-version. Per quell'upload intenzionale della baseline nativa, ometti--fail-on-incompatible(i pacchetti nativi dovrebbero cambiare). Mantieni--fail-on-incompatiblee--auto-min-update-versionnegli upload OTA quotidiani successivi. Vedi Workflow canale Native + OTA. - Mantieni allineate le regole di canale e semver per non spingere mai un bundle che presuppone le API di Cap 9 su dispositivi che eseguono ancora un vecchio shell nativo.
Se usi Build Capgo o la tua CI, aggiorna gli agenti prima il rilascio del Cap 9 store, in modo che la pipeline corrisponda a ciò che gli utenti installano: macOS i runner richiedono Node 24+ e Xcode 27+; Linux i runner richiedono Node 24+ e tooling Android allineato a AGP 9.2.1 / Gradle 9.5.1 (Xcode è disponibile solo su macOS).
Ordine operativo consigliato
- Aggiorna gli strumenti installati sui host CI e sulle macchine degli sviluppatori alle versioni minime indicate sopra (Node, Xcode, Android Studio, JDK). Non portare la dipendenza AGP, il Gradle wrapper o altri file del progetto Android dell'app Cap 8 ai valori di Cap 9 finché
bunx cap migrate— quelle modifiche al progetto fanno parte della fase di migrazione. - Correggi le API native deprecate nell'app code e nei plugin (soprattutto quelli custom
AppDelegategestione URL e utilizzo del bridge Android). - Pulizia Android Gradle file e script (
gradle.properties, valori predefiniti ProGuard,--urlnei script di dev). - Audit di Cordova utilizzo a livello di app; non modificare i prodotti SPM Cordova dei plugin fino alle release solo Cap 9.
- Quando Cap 9 sarà GA (o quando accetti
next), eseguibun add -d @capacitor/cli@next(o@latestdopo il rilascio), poibunx cap migrate, e segui Aggiornamento alla versione 9.0. - Pubblica il build nativo di Cap 9 negli store, poi riprendi o espandi i rollout OTA di Capgo sul canale corrispondente.
Capacitor 9 è in gran parte “risolvere le deprecazioni e allinearsi alle toolchain moderne di Android e Apple”. Eseguire quel lavoro su Cap 8 mantiene la diff di aggiornamento piccola e i plugin compatibili con i team che oggi stanno ancora rilasciando 8.x.