Preparazione a Capacitor 9: cosa possono fare le squadre di App e Plugin adesso

Capacitor 9 è disponibile su dist-tag mentre si muove verso la disponibilità generale. Non è necessario aggiornare l'app il giorno in cui l'alpha atterra, ma l'aggiornamento ufficiale di Capacitor 9 e la guida di aggiornamento del plugin già spiegano i pavimenti delle catene di strumenti e le rimozioni di Capacitor che meritano di essere affrontate presto. next dist-tag mentre si muove verso la disponibilità generale. Non è necessario aggiornare il tuo app il giorno in cui l'alpha viene rilasciato, ma official Capacitor 9 update guide and Guida all'aggiornamento dei plugin già elencare le piattaforme di sviluppo e le rimozioni di API che meritano di essere affrontate in anticipo.

Questo articolo è un'introduzione preparation elenco di controllo: lavoro che puoi fare su Capacitor 8 (o su una branch) affinché l'eventuale bunx cap migrate pass è noioso al posto di doloroso. Quando sei pronto a effettuare il passaggio, segui le guide di Ionic sopra menzionate linea per linea.

Strumentazione e piattaforme (applicazioni)

Pianifica il tuo CI, le macchine locali e le pipeline di archiviazione in base a questi minimi:

If sei ancora su Capacitor 8.4 o precedente per iOS, hai anche bisogno di Ciclo di vita della scene di interfaccia utente lavora dall'aggiornamento Capacitor 8.5 prima di Cap 9 — Xcode 27 lo aspetta. Le app già su 8.5 possono saltare quel passo aggiuntivo.

On iOS, Swift 6 (con Xcode 27) rifiuta @UIApplicationMain; quando aggiorni, sostituiscilo con @main in 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 è solamente collegato alla tua app quando cap sync detects un plugin Cordova installato. Android elimina i moduli Gradle aggiuntivi quando non sono presenti; iOS smette di aggiungere CapacitorCordova al Podfile o Package.swift quando non sono presenti.

Quello è un app-level Cordova (le tue o una plugin forzata) che importano simboli di Cordova senza un plugin Cordova reale nel progetto — quelle riferenze falliranno una volta che si applica l'impostazione di cavo Cordova facoltativa. custom native code (yours or a forked plugin) imports Cordova symbols without an actual Cordova plugin in the project — those references will fail once optional Cordova wiring applies.

Android: gradle.properties e AGP 9 di default

L'assistente per l'aggiornamento AGP scrive spesso esplicitamente gradle.properties flags così i build mantengono il comportamento di AGP 8. Capacitor 9 app dovrebbero app-level quelle entrate invece di portarle avanti: la maggior parte sono obsolete rispetto ad AGP 10, e alcune rompono i build di Cap 9 (ad esempio) android.builtInKotlin=false disabilita il supporto Kotlin che AGP 9 include, e android.sdk.defaultTargetSdkToCompileSdkIfUnset=false ferma AGP dall'inferire targetSdkVersion).

Quando migri, aspettati anche di:

• Aumenta variables.gradle le minime (compilazione/obiettivo SDK 37, minSdkVersion 26, versioni aggiornate di AndroidX — vedi la documentazione ufficiale).
• Elimina esplicitamente targetSdkVersion dal progetto build.gradle così che AGP 9 possa inferirlo da compileSdkVersion.
• Declara variables.gradle simboli in cima a app/build.gradle (Gradle 9.6 deprecato implicito di ricerca dal progetto root).
• Sostituisci i nomi predefiniti dei file ProGuard, migra core-ktx a androidx.core:core 1.19.0+, elimina l'uso del plugin Gradle Kotlin standalone e elimina jcenter().

Potrai leggere le differenze in blocchi di diffusione nel Aggiornamento a 9.0 Sezione Android e applica le stesse pulizie su una branch prima di aumentare le versioni Capacitor.

CLI: cap run --url

Capacitor 9 fonde le bandiere di caricamento live/host/port/https in un singolo --url argomento. Invece di:

bunx cap run android -l --host 192.168.1.181 --port 5173

passa l'URL che il tuo server di sviluppo stampa:

bunx cap run android --url http://192.168.1.181:5173/

Aggiorna i script e i frammenti README ora per evitare che la memoria muscolare si opponga al nuovo CLI dopo l'aggiornamento.

Plugin ufficiali: trappole per push e splash

Due modifiche visibili dagli utenti si verificano spesso nelle app di produzione:

Avvisi Push (iOS): Il deprecato alert opzione di presentazione è stata rimossa. Utilizza banner e/o list Schermo di Splash (Android):

Il valore predefinito è cambiato da launchFadeOutDuration modifiche da 200 ms a 0Se hai dipinto sulla scomparsa dei glitch del primo paint, impostalo launchFadeOutDuration: 200 esplicitamente in capacitor.config until you adjust your startup UI.

Scansiona le sezioni dei plugin nel 9.0 aggiornamento della guida per gli aggiornamenti delle versioni AndroidX e Google Play Services legati ai plugin ufficiali che utilizzi.

Manutentori dei plugin: preparati su Cap 8 senza rompere Cap 8

Se distribuisci Capacitor plugin consumati su Capacitor 8 e vuoi un code pronto per Capacitor 9, concentriamoci su Rimozione API obsoletarimozione dei __CAPGO_KEEP_0__ deprecata

, non sulle modifiche di packaging esclusive di Cap-9.

• Sostituisci @NativePlugin con @CapacitorPlugin e migra le API di autorizzazione/risultati attività legacy a @PermissionCallback / @ActivityCallback modelli (vedi la guida del plugin 9.0 tabella).
• Elimina PluginCall.hasOption, Plugin.getConfigValue, old CapConfig costruttori e getter, PluginCall.save() / isSaved()e altre rimozioni Java elencate sotto “Cambiamenti di rotta in code.”
• classe di compatibilità e le funzionalità obsolete CAPBridge compatibilità di classe e obsoleti CAPBridgeProtocol aiuto; utilizzo ApplicationDelegateProxy, digitato PluginCall gli accessori e le proprietà di bridge dalla tabella di migrazione.
• Esegui bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

Non rimuovere il Cordova prodotto SPM dal tuo plugin Package.swift Mentre ancora supportate la versione Capacitor 8. Progetti Cap 8 aspettano quella dipendenza quando il tuo plugin è basato su SPM; eliminarla in anticipo rompe i consumatori ancora su 8. rimuovere Cordova / rimozione condizionale Cordova product come un Capacitor 9-esimo la linea di rilascio (o un maggior semver esplicitamente documentato come Cap 9+), dopo aver smesso di supportare Cap 8 — come descritto nella guida del plugin, non come lavoro di preparazione sulla linea Cap 8.

La stessa regola di base si applica all'aumento capacitor-swift-pm di 9.0.0-alpha.x in Package.swiftQuesto elemento dovrebbe essere presente nella versione Cap 9, non nella versione compatibile con Cap 8.

Capgo live updates and the native Cap 9 store build

Capgo aggiornamenti in tempo reale e la costruzione nativa di Cap 9 del store pacchetto web aggiornamenti in tempo reale; la shell nativa continua a provenire dall'App Store e da Google Play. Quando sposterai l'app sul Capacitor 9:

1. Ship Spedisci (Ship) con almeno una costruzione di store compilato contro Capacitor 9 progetti nativi (iOS e Android). Quel binario stabilisce il baseline nativo Capgo per i canali di destinazione.
2. Solo dopo che il build è nelle mani degli utenti potete contare sulle bundle OTA testate contro Cap 9 WebView e comportamento dei plugin.
3. Posizionare i canali di produzione sulla metadata strategia e caricare il bundle di Cap 9 corrispondente su ogni canale con --auto-min-update-version. Per quel baseline nativo di upload intenzionale, omettere --fail-on-incompatible (i pacchetti nativi dovrebbero cambiare). Mantenere --fail-on-incompatible e --auto-min-update-version dopo gli upload OTA quotidiani. Vedi su ogni upload OTA quotidiano successivo. Vedi.
4. Keep channel and semver rules aligned so you never push a bundle that assumes Cap 9 APIs to devices still running an older native shell.

Se utilizzi Capgo Build o il tuo CI, aggiorna gli agenti prima the Cap 9 store release so the pipeline matches what users install: macOS i runner devono avere Node 24+ e Xcode 27+; Linux i runner devono avere Node 24+ e strumentazione Android host allineata con AGP 9.2.1 / Gradle 9.5.1 (Xcode è disponibile solo su macOS).

Suggerito ordine di operazioni

1. Aggiorna gli strumenti installati Sui host CI e sulle macchine dei developer, portali ai livelli successivi (Node, Xcode, Android Studio, JDK). Non Aumentare la dipendenza AGP dell'app Cap 8, il wrapper Gradle o altri file del progetto Android ai valori di Cap 9 fino a bunx cap migrate quando — quelle modifiche del progetto appartengono allo step di migrazione.
2. Correggi le API native obsolete in app code e plugin (soprattutto personalizzati) AppDelegate Pulisci i file e i script di Android Gradle
3. Pulisci Gradle Android impostazioni di default ProGuard,gradle.propertiesin script di sviluppo). --url in script di sviluppo).
4. Verifica Cordova utilizzo all'applicazione; non modificare plugin SPM per prodotti Cordova fino a rilasci Cap 9-esclusivi.
5. Quando Cap 9 sarà GA (o quando accetti next) bun add -d @capacitor/cli@next esegui @latest dopo l'uscita) bunx cap migratecontexto: frammento di testo HTML da una stringa di UI Capgo più lunga (chiave genitora `compare_step_build_text`). Pagina/area: sito web di marketing Capgo. Ruolo: paragrafo di marketing o legale lungo. Visto in: alternative di pagina expo.astro, alternative di pagina voltbuilder.astro. Chiave di messaggio `compare_step_build_text` (Testo di costruzione di confronto). dopo la release), quindi.
6. Pubblica l'edizione nativa di Cap 9 alla store, poi riprendere o espandere Capgo gli aggiornamenti OTA sul canale corrispondente.

Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.