Come aggiornare la tua app Capacitor a Capacitor 8

Per aggiornare un'app Capacitor a Capacitor 8, installa Node.js 22+, Xcode 26+ e Android Studio Otter, aggiorna @capacitor/cli all'ultima versione 8.x, esegui bunx cap migrate, quindi correggi quello che segnala il migratore. I principali breaking change sono iOS 15 come target di deployment minimo, Android SDK 36 con minSdk 24, AGP 8.13 con Gradle 8.14.3 e la rimozione di adjustMarginsForEdgeToEdge a favore del nuovo plugin System Bars.

Questa guida illustra il percorso automatizzato, ogni passaggio manuale che comporta e gli errori più frequenti dopo l'upgrade. Se gestisci un plugin invece di un'app, leggi Come aggiornare il tuo plugin Capacitor a Capacitor 8 invece.

Requisiti Capacitor 8 in breve

Controlla la toolchain prima di toccare il progetto. La maggior parte degli upgrade falliti è colpa di un vecchio JDK, di un vecchio Xcode o di un Node vecchio in CI, non di code.

Xcode 26 non è solo un requisito per Capacitor. Dal 28 aprile 2026, App Store Connect rifiuta gli upload compilati con una versione precedente di Xcode, quindi ti servirà comunque. Vedi Il requisito Xcode 26 di Apple per le app Capacitor per i dettagli.

Prima di iniziare

1. Commit tutto o crea una branch. Il migratore modifica i file nativi in loco.
2. Assicurati che l'app si compili su Capacitor 7 oggi. Aggiornare un progetto rotto aggiunge solo rumore.
3. Se sei su Capacitor 6 o versioni precedenti, esegui prima l'aggiornamento al major precedente. Ogni major ha la propria logica di migrazione nel CLI.
4. Elenca i tuoi plugin con bunx cap ls e verifica che ciascuno abbia una release che supporta Capacitor 8. Controlla il peerDependencies dell'ultima versione:

bun pm view @capgo/capacitor-updater peerDependencies

Un plugin con @capacitor/core: ^7.0.0 come peer verrà installato con avvisi e potrebbe non compilarsi. I plugin Capgo seguono il major di Capacitor nel proprio numero di versione, quindi @capgo/* le release 8.x sono destinate a Capacitor 8.

5. Aggiorna le toolchain locali e CI: Node 22, Xcode 26, JDK 21, Android Studio Otter. In GitHub Actions, fissa un'immagine macOS che includa Xcode 26 e usa actions/setup-java con java-version: '21'.

Opzione 1: aggiorna con cap migrate

Il CLI include un comando di migrazione che gestisce la maggior parte del lavoro. Installa l'ultima versione di CLI, poi eseguilo:

bun add -D @capacitor/cli@latest
bunx cap migrate

Il migratore chiede se installare i nuovi pacchetti Capacitor e ti permette di scegliere tra npm, Yarn, pnpm o Bun. Scegli Bun se il tuo progetto ha un bun.lock. Puoi saltare la domanda con bunx cap migrate --noprompt.

Cosa cambia per te:

• Aggiorna @capacitor/core, @capacitor/ios, @capacitor/android e i plugin ufficiali @capacitor/* plugin a 8.x.
• Imposta IPHONEOS_DEPLOYMENT_TARGET = 15.0 nel progetto Xcode e platform :ios, '15.0' nel Podfile.
• Aggiornamenti variables.gradle, la classpath AGP, il wrapper Gradle e kotlin_version.
• Aggiunge density a android:configChanges nella AndroidManifest.xml.

Leggi l'output completo. Se un passaggio non può essere applicato, ad esempio perché un file è stato personalizzato, CLI stampa un errore con il nome del file e prosegue. Quelle righe sono la tua lista di cose da fare manualmente.

Quando termina:

bun run build
bunx cap sync

Poi apri ogni piattaforma e fai un build una volta dall'IDE in modo da vedere gli errori nativi per intero.

Opzione 2: upgrade manuale

Se i tuoi progetti nativi sono fortemente personalizzati o se il migratore ha saltato dei passaggi, applica le modifiche manualmente. Queste corrispondono alle guida ufficiale all'upgrade di Capacitor 8.

Aggiorna i pacchetti npm

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

Poi aggiorna ogni plugin ufficiale, ad esempio:

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

iOS: porta il deployment target a 15.0

In Xcode, seleziona il progetto, apri Impostazioni di Build, trova Obiettivo di deployment iOS sotto Deployment e impostalo su 15.0. Ripeti per ogni target dell'app, incluse le estensioni.

Se l'app utilizza ancora CocoaPods, aggiorna ios/App/Podfile:

platform :ios, '15.0'

Poi esegui bunx cap sync ios, che esegue pod install per te.

Se l'app usa SPM, CLI rigenera ios/App/CapApp-SPM/Package.swift a ogni sync con la versione della piattaforma corretta e un capacitor-swift-pm versione che corrisponda a quella installata @capacitor/ios. Non modificare quel file manualmente.

iOS: rimuovi le notifiche dei view controller personalizzati

Capacitor 8 ora emette CAPBridgeViewController notifiche per viewDidAppear e viewWillTransition stesso. Se hai aggiunto un'estensione o una sottoclasse per postare .capacitorViewDidAppear oppure .capacitorViewWillTransition, eliminala, altrimenti i listener scatteranno due volte.

Android: aggiorna Android Studio e AGP

Installa Android Studio Otter o versioni successive, apri la android cartella ed esegui Strumenti > AGP Upgrade Assistant. Scegli 8.13.0 ed esegui i passaggi selezionati. Oppure modifica android/build.gradle direttamente:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

E android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

Android: aggiornamento variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

Mantieni tutte le variabili extra lette dai tuoi plugin (ad esempio firebaseMessagingVersion). I bump ufficiali dei plugin per Capacitor 8 includono firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' e androidxExifInterfaceVersion = '1.4.1'.

Android: passa a = l'assegnazione in file Gradle

Gradle ha deprecato la sintassi di assegnazione con spazio. Attualmente emette solo un warning, ma causerà un errore in una futura release di Gradle, quindi correggilo ora in android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

Le chiamate al metodo come google() oppure mavenCentral() restano invariate.

Android: Kotlin e configChanges

Se il modulo della tua app usa Kotlin, imposta kotlin_version = '2.2.20'. Kotlin 2.x trasforma il vecchio kotlinOptions {} in un errore, quindi sposta jvmTarget all'interno kotlin { compilerOptions { ... } }.

Aggiungi quindi density all'attività principale, in modo che il WebView non venga ricreato al cambio di densità dello schermo (foldable, ridimensionamento finestra, impostazioni dimensione display):

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android: il layout del bridge è stato rinominato

bridge_layout_main.xml non esiste più. Se il tuo MainActivity o un frammento personalizzato di riferimento R.layout.bridge_layout_main, usa R.layout.capacitor_bridge_layout_main.

Edge-to-edge e il nuovo plugin System Bars

Questa è la modifica più probabile da notare visivamente. Capacitor 8 ha rimosso android.adjustMarginsForEdgeToEdge e aggiunto un plugin System Bars core. Non va installato, è incluso in @capacitor/core.

Android 15 impone edge-to-edge per le app che targettizzano SDK 35, e Android 16 rimuove l'opt-out per le app che targettizzano SDK 36. Capacitor 8 targettizza 36, quindi il tuo contenuto web viene ora disegnato dietro le barre di stato e di navigazione a meno che non gestisci gli insets.

La configurazione del plugin si trova sotto plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

Con css oppure native, i WebView Android più recenti (Chromium 140+) rispettano viewport-fit=cover e riportano valori reali di env(safe-area-inset-*) Sui WebView più vecchi, Capacitor applica un padding al WebView e imposta i valori env a 0px. Imposta quindi il meta tag e usa le variabili:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

A runtime puoi cambiare lo stile o la visibilità della barra:

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Le app Ionic Framework usano già le variabili safe-area, quindi di solito hanno bisogno solo del meta tag. Il nostro vecchio post su edge-to-edge senza plugin descrive l'opzione Capacitor 7, che non esiste più in 8.

Altre modifiche comportamentali da verificare

• appendUserAgent su iOS: Capacitor 7 aggiungeva due spazi prima della stringa, Capacitor 8 ne aggiunge uno. Se il tuo server analizza l'user agent in modo rigoroso, aggiungi uno spazio iniziale a ios.appendUserAgent (non l'opzione root, che influisce anche su Android).
• Screen Orientation e Barcode Scanner: su Android 16+ con schermi grandi, i lock di orientamento vengono ignorati. Esiste un opt-out temporaneo tramite la android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY proprietà manifest, ma Android 17 la rimuove.
• Geolocalizzazione: timeout ora si applica a tutte le richieste su Android e iOS. Se noti nuovi timeout, aumenta il valore. watchPosition su Android ha acquisito un interval opzione.
• Barra di stato: il plugin non include più i propri CAPBridgeViewController file di notifica, dato che il core ora emette questi eventi.
• Le nuove piattaforme iOS usano SPM di default: bunx cap add ios ora crea un progetto SPM. Usa --packagemanager CocoaPods se hai bisogno del vecchio template. Vedi come usare CocoaPods con Capacitor 8.

Verifica l'upgrade

Passa in rassegna questa lista su entrambe le piattaforme prima del rilascio:

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor mostra le versioni 8.x corrispondenti per core, CLI, iOS e Android.
• L'app si avvia, la splash screen scompare, i deep link aprono la schermata corretta.
• Status bar e navigation bar appaiono correttamente su dispositivi Android 15/16 e iPhone con notch.
• Push notification, fotocamera, accesso ai file e qualsiasi plugin con permessi nativi funzionano ancora.
• Una build release (Archive in Xcode, ./gradlew bundleRelease") ha successo, non solo il debug.")

Se non vuoi mantenere Xcode 26 e JDK 21 su ogni macchina, Build Capgo esegue le build iOS e Android nel cloud con le toolchain attuali.

Distribuisci l'upgrade in sicurezza con i Live Updates

Un major upgrade di Capacitor cambia i code nativi, quindi deve passare dall'App Store e da Google Play. I web bundle creati dopo l'upgrade potrebbero chiamare API dei plugin che i binari più vecchi non hanno.

Se usi Live updates di Capgo, tieni separati gli utenti di Capacitor 7 e quelli di Capacitor 8 finché l'adozione non sarà completa: incrementa la versione nativa, carica i nuovi bundle su un canale usato dal nuovo binario e avvia il controllo di compatibilità prima di caricare:

bunx @capgo/cli@latest bundle compatibility

Confronta le versioni dei plugin nativi nel tuo bundle con quelle attive sul canale e segnala eventuali discrepanze prima che gli utenti ricevano un aggiornamento non funzionante.

Risoluzione dei problemi comuni durante l'aggiornamento a Capacitor 8

The engine "node" is incompatible oppure CLI si rifiuta di avviarsi. Stai usando Node 20 o una versione precedente. Installa Node 22 LTS e aggiorna anche l'immagine della tua CI.

error: invalid source release: 21 su Android. Gradle sta girando con JDK 17. Imposta Android Studio per usare il JDK 21 incluso (Impostazioni > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK) e imposta JAVA_HOME a JDK 21 per build da riga di comando e CI.

Minimum supported Gradle version is 8.13. Hai aggiornato AGP ma non il wrapper. Imposta il wrapper su 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion è ancora 35 da qualche parte. Controlla variables.gradle e qualsiasi plugin che lo hardcode.

Using 'kotlinOptions' ... is an error o errori simili nel Kotlin DSL. Un plugin o il modulo dell'app usa ancora kotlinOptions. Aggiorna il plugin o applica una patch finché non esce una release (vedi come patchare un plugin Capacitor).

Xcode: No such module 'Capacitor' dopo l'upgrade. Per CocoaPods, apri App.xcworkspace, non App.xcodeproj, e riesegui bunx cap sync ios. Per SPM, usa File > Package > Reset Package Caches.

"X" plugin is not implemented on ios/android. Il plugin non è stato sincronizzato o non ha una release compatibile con Capacitor 8 / SPM. Esegui bunx cap sync e leggi i warning.

Per un elenco più completo, consulta Guida alla risoluzione problemi iOS di Capacitor e il Guida alla risoluzione dei problemi Android. Le versioni non corrispondenti tra core e plugin sono trattate in risolvere gli errori di Capacitor version mismatch.

Lascia che un agente AI si occupi delle parti noiose

Se usi Claude Code, Cursor o un agente simile, l'open Competenze Capgo includono capacitor-app-upgrade-v7-to-v8 e capacitor-app-upgrades per salti multi-major. Installali con bunx skills add Cap-go/capgo-skills e chiedi all'agente di aggiornare l'app. Esegue il migrator, poi controlla i passaggi che CLI di solito tralascia, come la sintassi Gradle, le opzioni Kotlin e le immagini CI.

Cosa viene dopo

Capacitor 9 è già in prerelease. Una volta stabile sulla 8, leggi Prepararsi a Capacitor 9 così il prossimo upgrade sarà più leggero.