Salta al contenuto principale
Capacitor

Prepararsi per Capacitor 9: cosa possono fare ora i team di app e plugin

Capacitor 9 alza l'asticella su Node, Xcode, Android Gradle e sulle API native deprecate. Ecco come prepararsi su Capacitor 8 prima di cambiare versione, inclusa la sync opzionale di Cordova, il live reload di CLI e i build OTA per gli store di Capgo.

Prepararsi a Capacitor 9: cosa possono fare ora i team di app e plugin Capgo illustrazione blog

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.gradle minimi (compile/target SDK 37, minSdkVersion 26, versioni AndroidX aggiornate — vedi la doc ufficiale).
  • Rimuovi l'esplicito targetSdkVersion from the app build.gradle così AGP 9 può inferirlo da compileSdkVersion.
  • Dichiara variables.gradle i simboli in cima a app/build.gradle (Gradle 9.6 depreca il lookup implicito dal progetto root).
  • Sostituisci i nomi dei file ProGuard predefiniti, migra core-ktx a androidx.core:core 1.19.0+, abbandona l'uso del plugin Kotlin Gradle standalone e rimuovi jcenter().

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 @NativePlugin con @CapacitorPlugin e migra le API legacy permission / activity-result ai @PermissionCallback / @ActivityCallback pattern (vedi la tabella della guida al plugin 9.0 ).
  • Rimuovi PluginCall.hasOption, Plugin.getConfigValue, vecchi CapConfig costruttori e getter, PluginCall.save() / isSaved(), e altre rimozioni Java elencate in “Modifiche incompatibili in code”.
  • Su iOS, smetti di usare la CAPBridge classe di compatibilità e gli CAPBridgeProtocol helper deprecati; usa ApplicationDelegateProxy, tipizzato PluginCall e proprietà bridge dalla tabella di migrazione.
  • Esegui bunx @capacitor/plugin-migration-v8-to-v9@latest su 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:

  1. 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.
  2. 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.
  3. Imposta i canali di produzione sulla metadata strategia 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-incompatible e --auto-min-update-version negli upload OTA quotidiani successivi. Vedi Workflow canale Native + OTA.
  4. 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

  1. 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.
  2. Correggi le API native deprecate nell'app code e nei plugin (soprattutto quelli custom AppDelegate gestione URL e utilizzo del bridge Android).
  3. Pulizia Android Gradle file e script (gradle.properties, valori predefiniti ProGuard, --url nei script di dev).
  4. Audit di Cordova utilizzo a livello di app; non modificare i prodotti SPM Cordova dei plugin fino alle release solo Cap 9.
  5. Quando Cap 9 sarà GA (o quando accetti next), esegui bun add -d @capacitor/cli@next (o @latest dopo il rilascio), poi bunx cap migrate, e segui Aggiornamento alla versione 9.0.
  6. 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.

Live updates per le app Capacitor

Quando un bug nel web-layer è live, rilascia la fix tramite Capgo invece di aspettare giorni l'approvazione degli store. Gli utenti ricevono l'update in background, mentre le modifiche native restano nel normale processo di review.

Ultimi articoli dal blog

Capgo ti offre gli insight migliori che ti servono per creare un'app mobile davvero professionale.