Risolvere gli errori di Capacitor Android: errori comuni e soluzioni

La maggior parte degli errori di compilazione Capacitor Android deriva da una malfunzionante catena di strumenti: JDK sbagliato, wrapper Gradle vecchio o livello SDK che non corrisponde a quanto richiesto da una dipendenza. Per Capacitor 8, utilizzare JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk e targetSdk 36 e minSdk 24, quindi eseguire bunx cap sync android e leggere il primo errore Gradle, non l'ultimo.

Questa guida elenca gli errori Android più comuni che si verificano nei progetti Capacitor , raggruppati per dove si verificano: configurazione Gradle, risoluzione delle dipendenze, compilazione, installazione e esecuzione. Per iOS, vedere il Capacitor Guida di risoluzione dei problemi per iOS.

Checklist di triage rapido

bunx cap doctor              # core, CLI and android must share the same major
node -v                      # 22+ for Capacitor 8
java -version                # 21 for Capacitor 8
bun run build && bunx cap sync android
cd android && ./gradlew assembleDebug --stacktrace

Verifica quindi i valori attesi per la tua versione di Capacitor:

Se sei in fase di aggiornamento, segui Come aggiornare il tuo Capacitor App a Capacitor 8 prima.

Errori Gradle e JDK

error: invalid source release: 21

Gradle funziona con JDK 17 o precedente, ma @capacitor/android 8 compila con Java 21. In Studio Android: Impostazioni > Costruzione, esecuzione e distribuzione > Strumenti di costruzione > Gradle > Gradle JDK e seleziona il JDK 21 incorporato (Runtime JetBrains). In linea di comando e in CI:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS

# GitHub Actions
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'

Unsupported class file major version 65

The problema inverso: esegui JDK 21 con un wrapper Gradle troppo vecchio per leggere file di classe Java 21. Aggiorna il wrapper:

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

Minimum supported Gradle version is 8.13. Current version is 8.11.1

AGP è stato aggiornato, ma il wrapper non lo è stato. Ogni versione di AGP ha una versione minima di Gradle, e AGP 8.13 richiede Gradle 8.13+. Imposta il wrapper a 8.14.3 come sopra.

The project is using an incompatible version (AGP 8.13.0) of the Android Gradle plugin

Il tuo Android Studio è più vecchio dell'AGP presente nel progetto. Installa Android Studio Otter o una versione più recente.

SDK location not found

Gradle non riesce a trovare l'Android SDK. Apri il progetto una volta in Android Studio (lo scrive android/local.properties) o impostalo manualmente:

export ANDROID_HOME="$HOME/Library/Android/sdk"

Non commettere local.properties contiene una percorso specifico della macchina.

Could not resolve all files for configuration / Could not GET https://dl.google.com/...

Problema di rete o repository. Controlla le impostazioni del proxy in ~/.gradle/gradle.propertiesassicurati google() e mavenCentral() controlla che repositoriese riprova con --refresh-dependenciesLe reti corporate spesso hanno bisogno di un mirror.

Java heap space o GC overhead limit exceeded

Aumenta la memoria di Gradle android/gradle.properties:

org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8

Il template Capacitor viene fornito con -Xmx1536mIl template __CAPGO_KEEP_0__ viene fornito con

Error di dipendenza e livello di SDK

Dependency 'androidx.core:core:1.17.0' requires libraries and applications that depend on it to compile against version 36 or later

compileSdkVersion Ecco il valore che un'istanza di AndroidX richiede. Impostalo a 36 in variables.gradleè inferiore a quanto serve a una libreria AndroidX. Impostalo a 36 in aggiornare il file build.gradle.

Manifest merger failed : uses-sdk:minSdkVersion 23 cannot be smaller than version 24 declared in library

Il tuo app minSdkVersion La versione è inferiore a quella di una dipendenza. Capacitor 8 richiede 24. Alzalo in variables.gradle.

Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules

che è inferiore a quello di una dipendenza. __CAPGO_KEEP_0__ 8 richiede 24. Alzalo in kotlin-stdlib-jdk8Allinea su una versione di Kotlin. Imposta kotlin_version = '2.2.20' in la tua root build.gradle (i plugin la leggono tramite rootProject.ext) e aggiorna i plugin che fissano Kotlin 1.x. Se necessario, forza il BOM in android/app/build.gradle:

dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.2.20"))
}

Duplicate class com.google.android.gms... o com.google.firebase...

Due a due plugin portano versioni diverse di Play Services o Firebase. La maggior parte dei Capacitor plugin legge le versioni da variables.gradle (ad esempio) firebaseMessagingVersion), quindi definiscile una volta per tutte in modo che ogni plugin utilizzi lo stesso valore.

Project with path ':capacitor-xxx' could not be found in project ':app'

android/capacitor.settings.gradle ) android/app/capacitor.build.gradle Sono fuori data. Entrambi sono generati. Esegui bunx cap sync androide File > Sincronizza Progetto con File Gradle.

Error di compilazione

Namespace not specified. Specify a namespace in the module's build file

AGP 8+ richiede namespace in ogni modulo Android. I vecchi plugin dichiarano solo package in loro AndroidManifest.xmlAggiorna il plugin. Se non esiste una versione rilasciata, aggiorna la sua android/build.gradle:

android {
    namespace = "com.example.plugin"
}

e rimuovi l'attributo package da il suo manifesto.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17) jvm target compatibility should be set to the same Java version

Un modulo Kotlin (il tuo o di un plugin) ha un jvmTarget differente dal suo targetCompatibilityJava. In Kotlin 2.x, impostalo con compilerOptions:

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21
    }
}

La vecchia kotlinOptions {} è un errore in Kotlin 2.2, quindi i plugin che ancora la utilizzano hanno bisogno di un aggiornamento o di una patch.

Errori relativi a proguard-android.txt con AGP 9

Se hai già migrato a AGP 9, i plugin che si riferiscono a getDefaultProguardFile('proguard-android.txt') falliscono. La soluzione è proguard-android-optimize.txt. Dettagli completi in risolvi gli errori di build del plugin Capacitor con AGP 9. Per le app Capacitor 8, rimane la versione AGP 8.13 testata.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 ha rinominato la layout in capacitor_bridge_layout_main. Aggiorna la referenza nella tua MainActivity o frammento personalizzato.

android:exported needs to be explicitly specified for element <activity#...>

Le app che mirano a Android 12+ devono impostare android:exported su ogni attività, servizio e ricevitore con un filtro di intento. Aggiungi android:exported="true" (o falseverifica il tuo manifesto. Se l'elemento proviene da un manifesto di plugin, aggiorna o patcha il plugin.

Errori di installazione

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Un'app con lo stesso ID ma una chiave di firma diversa è installata, di solito una versione di rilascio dal Play Store rispetto alla tua versione di debug. Disinstallala per primo:

adb uninstall com.example.app

Non è elencato il dispositivo in Android Studio o adb devices mostra unauthorized

Abilita le opzioni dello sviluppatore e il debug USB, accetta la richiesta di chiave RSA sul telefono e utilizza un cavo dati. adb kill-server && adb start-server risolve la maggior parte degli stati bloccati.

Console Google Play: "L'app non supporta le dimensioni di pagina di memoria da 16 KB"

Un nativo .so La tua libreria non è allineata a 16 KB. Trova il plugin che la fornisce e aggiorna. Vedi Dimensioni di pagina di memoria Android 16 KB e plugin Capacitor.

La firma di un rilascio di build

I impostazioni del keystore mancanti o sbagliate causano Keystore file not found o Failed to read key. Il nostro Generatore di keystore Android crea un keystore e la configurazione di firma Gradle. Conserva il keystore fuori da Git e salvalo. Perdere il keystore significa che non potrai aggiornare l'app a meno che non utilizzi la firma di App Play.

Errori di esecuzione

"X" plugin is not implemented on android

1. Il plugin è in package.json e hai eseguito bunx cap sync android dopo averlo installato.
2. Android Studio ha sincronizzato Gradle dopo la sincronizzazione ("File > Sincronizza progetto con file Gradle).
3. Il plugin compare in android/capacitor.settings.gradle.
4. La versione del plugin corrisponde al tuo Capacitor maggiore. Un plugin Capacitor 7 può compilare ma registrarsi in modo diverso.
5. Non stai eseguendo un vecchio APK. Disinstalla e reinstalla.

Schermo bianco vuoto

Apri chrome://inspect e controlla il console del WebView. Cause comuni:

• net::ERR_CLEARTEXT_NOT_PERMITTED durante il live reload: Android blocca i protocolli HTTP. Per lo sviluppo solo, impostare server.cleartext: true nella configurazione Capacitor, e rimuovere server.url prima della release.
• Server di sviluppo non raggiungibile: assicurati di 0.0.0.0utilizza l'indirizzo IP della rete locale, mantieni telefono e computer sulla stessa rete, o avvia il port con bunx cap run android --forwardPorts 5173:5173.
• Vecchio WebView di Android: Capacitor controlla android.minWebViewVersion (default 60) e registra un errore nei vecchi WebViews. I dispositivi che non aggiornano mai il WebView possono anche fallire con il JavaScript moderno. plugin di controllo della versione del WebView può rilevare WebView obsoleti e sollecitare gli utenti all'aggiornamento.
• Target di costruzione troppo nuovo per il WebView del dispositivo. Abbassare il target del bundler o aggiungere polifilli.
• Wrong webDir: controlla android/app/src/main/assets/public contiene index.html.
• Bundle live update rotto: con Capgo, un bundle che non chiama mai notifyAppReady() è annullato automaticamente dopo il timeout. Vedi i documenti dell'aggiornatore.

Contenuto dietro la barra di stato o la barra di navigazione

Applicazioni che puntano a SDK 35+ disegnano dall'orlo all'orlo su Android 15, e Android 16 ha eliminato l'opzione di esclusione per le app che puntano a SDK 36. Capacitor 8 ha eliminato adjustMarginsForEdgeToEdge. Gestisci gli insetti con la configurazione del plugin System Bars e CSS:

plugins: {
  SystemBars: {
    insetsHandling: 'css',
    initialViewportFitValueHint: 'cover',
  },
},

<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);
}

Con insetsHandling: 'css', Capacitor inietta anche --safe-area-inset-* variabili CSS, che aiuta nelle vecchie viste Web dove env() reporta zero.

Ricarica WebView quando si ruota o si ridimensiona

La attività viene ricreata. Controlla android:configChanges se l'attività principale include density (aggiunto in Capacitor 8) insieme a orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Ignorato l'blocco di orientamento sui tablet

Le grandi schermate ignorano i blocchi di orientamento per le app che puntano a SDK 36. Esiste un'opzione di manifest per l'ottimizzazione temporanea (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), ma Android 17 lo elimina. Progettare per entrambe le orientazioni sulle grandi schermate.

Come debuggare quando l'errore non è elencato

1. Leggi l'errore più importante. Esegui ./gradlew assembleDebug --stacktrace e scorri verso l'alto fino all'errore più importante. FAILURE o What went wrong.
2. Verifica la tabella delle dipendenze per conflitti di versione: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtered per il tuo pacchetto per crash native. Capacitor registra le chiamate del plugin con il Capacitor tag.
4. chrome://ispezionare per errori JavaScript.
5. Isola con una nuova bun create @capacitor/app Ulteriori strumenti sono trattati nella

guida definitiva per il debug dei __CAPGO_KEEP_0__ app ultimate guide to debugging Capacitor apps and Come risolvere gli errori di build Android in CapacitorSe i tuoi macchinari CI sono il problema piuttosto che il code. Capgo Costruzione SDK esegue costruzioni Android con il JDK giusto e SDK già installato.