Capacitor : Résolution des erreurs Android courantes

La plupart des erreurs de construction Android Capacitor proviennent d'une incompatibilité de la chaîne d'outils : le JDK incorrect, un wrapper Gradle ancien ou un niveau SDK qui ne correspond pas à ce dont une dépendance a besoin. Pour Capacitor 8, utilisez JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk et targetSdk 36 et minSdk 24, puis exécutez bunx cap sync android et lisez la première erreur Gradle, pas la dernière.

Cette guide liste les erreurs Android que nous voyons le plus souvent dans les projets Capacitor , regroupées par où elles se produisent : configuration Gradle, résolution de dépendances, compilation, installation et exécution. Pour iOS, voir le Capacitor guide de dépannage iOS.

Liste de vérification rapide

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

Vérifiez ensuite les valeurs attendues pour votre version Capacitor :

Si vous êtes en cours d'actualisation, suivez Comment mettre à jour votre application Capacitor vers Capacitor 8 Gradle et JDK

Erreurs de Gradle et JDK

error: invalid source release: 21

8 compile avec Java 21. Dans Android Studio : @capacitor/android 8 compile avec Java 21. Dans Android Studio : et choisissez le JDK 21 fourni (Runtime JetBrains). Sur la ligne de commande et dans CI : et choisissez le JDK 21 (Runtime JetBrains) intégré. Dans la ligne de commande et dans 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

Le problème inverse : vous exécutez JDK 21 avec un wrapper Gradle trop ancien pour lire les fichiers de classe Java 21. Mettez à jour le 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 a été mis à jour mais le wrapper ne l'a pas été. Chaque version d'AGP a une version minimale de Gradle, et AGP 8.13 nécessite Gradle 8.13+. Définissez le wrapper sur 8.14.3 comme ci-dessus.

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

Votre édition d'Android Studio est plus ancienne que l'AGP du projet. Installez Android Studio Otter ou une version plus récente.

SDK location not found

Le Gradle ne peut pas trouver l'Android SDK. Ouvrez le projet une fois dans Android Studio (il s'écrit) android/local.properties), ou définissez la variable :

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

Ne commettez pas local.propertiesIl contient un chemin spécifique à la machine.

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

Problème de réseau ou de dépôt. Vérifiez les paramètres de proxy dans ~/.gradle/gradle.propertiesassurez-vous que google() et mavenCentral() sont en repositories, et réessayer avec --refresh-dependenciesLes réseaux corporatifs ont souvent besoin d'un miroir.

Java heap space ou GC overhead limit exceeded

Augmentez la mémoire de Gradle android/gradle.properties:

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

Le Capacitor modèl’est livré avec -Xmx1536m, qui est serré pour les applications avec de nombreux plugins.

Erreurs de dépendance et niveau de SDK

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

compileSdkVersion C'est la valeur que nécessite une bibliothèque AndroidX. Fixez-l’à 36 dans variables.gradleSi l'erreur nomme un module de plugin, ce plugin fixe une valeur ancienne. Mettez-l’à jour, ou corriger son build.gradle.

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

ou minSdkVersion La valeur est inférieure à celle d'une dépendance. Capacitor 8 nécessite 24. Augmentez-l’en variables.gradle.

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

Deux artefacts de bibliothèque standard Kotlin avec des classes en chevauchement, généralement en raison d'une ancienne version d'un plugin. kotlin-stdlib-jdk8Alignez-vous sur une version Kotlin unique. Mettez. kotlin_version = '2.2.20' dans votre racine build.gradle (plugins le lisent via) rootProject.ext) et mettez à jour les plugins qui fixent Kotlin 1.x. Si nécessaire, forcez le BOM dans android/app/build.gradle:

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

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

Deux plugins apportent des versions différentes de Play Services ou Firebase. La plupart des Capacitor plugins lisent les versions de variables.gradle par exemple firebaseMessagingVersion), définit-les une fois là-bas afin que chaque plugin utilise la même valeur.

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

android/capacitor.settings.gradle and android/app/capacitor.build.gradle Les deux sont générés. Exécutez. bunx cap sync androidcontext Fichier > Synchroniser le projet avec les fichiers Gradle.

Erreurs de compilation

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

AGP 8+ nécessite namespace en chaque module Android. Les anciens plugins ne déclarent package en leur AndroidManifest.xmlMettez à jour le plugin. Si aucune mise à jour n'est disponible, corrigez-le. android/build.gradle:

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

de son manifeste. package attribut de son manifeste.

'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 module Kotlin (le vôtre ou celui d'un plugin) a une version différente jvmTarget Java. Dans Kotlin 2.x, définissez-l’avec targetCompatibility. Dans Kotlin 2.x, définissez-le compilerOptions:

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

l'ancien kotlinOptions {} Il s'agit d'une erreur en Kotlin 2.2, donc les plugins qui l'utilisent encore doivent être mis à jour ou corrigés.

Problèmes liés à proguard-android.txt avec AGP 9

Si vous avez déjà migré vers AGP 9, les plugins qui référencent getDefaultProguardFile('proguard-android.txt') échouent. La solution est proguard-android-optimize.txt. Détails complets dans corriger les erreurs de build du plugin Capacitor avec AGP 9. Pour les applications Capacitor 8, AGP 8.13 reste la version testée.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 a renommé la disposition en capacitor_bridge_layout_mainMettez à jour la référence dans votre MainActivity ou fragment personnalisé.

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

Les applications ciblées Android 12+ doivent définir android:exported sur chaque activité, service et récepteur avec un filtre d'intent. Ajoutez android:exported="true" (or false) dans votre manifest. Si l'élément provient d'un manifest de plugin, mettez à jour ou corrigez le plugin.

Erreurs d'installation

INSTALL_FAILED_UPDATE_INCOMPATIBLE

An app with the same ID but a different signing key is installed, usually a release build from the Play Store versus your debug build. Uninstall it first:

adb uninstall com.example.app

Appareil non listé dans Android Studio ou adb devices shows unauthorized

Activer les options de développeur et la débogage USB, accepter la prompte RSA sur le téléphone et utiliser un câble capable de données. adb kill-server && adb start-server corrige la plupart des états bloqués.

Play Console: “Your app does not support 16 KB memory page sizes”

Un natif .so La bibliothèque de votre application n'est pas alignée sur 16 Ko. Trouvez le plugin qui la fournit et mettez-l’à jour. Voir Taille de page Android 16 Ko et plugins Capacitor.

Signature d'une mise en production

Missing or wrong keystore settings cause Keystore file not found ou Failed to read key. Our Générateur de clés de signature Android creates a keystore and the Gradle signing config. Keep the keystore out of git and back it up. Losing it means you can’t update the app unless you use Play App Signing.

Le plugin est dans

"X" plugin is not implemented on android

1. et vous avez exécuté package.json and you ran bunx cap sync android Les erreurs de temps d'exécution
2. Les erreurs de temps d'exécutionLes erreurs de temps d'exécution).
3. Le plugin apparaît dans android/capacitor.settings.gradle.
4. La version du plugin correspond à votre Capacitor majeur. Un plugin Capacitor 7 peut compiler mais s'enregistrer différemment.
5. Vous n'avez pas installé une ancienne version. Déinstallez et réinstallez.

Écran blanc vide

Ouvrez chrome://inspect et vérifiez la console du WebView. Les causes courantes :

• net::ERR_CLEARTEXT_NOT_PERMITTED during live reload: Android blocks plain HTTP. For development only, set server.cleartext: true dans la configuration Capacitor et supprimez server.url avant la mise en production.
• Serveur de développement inaccessible : liez-l’à 0.0.0.0utilisez votre adresse IP LAN, gardez votre téléphone et votre ordinateur sur le même réseau, ou redirigez le port avec bunx cap run android --forwardPorts 5173:5173.
• Ancienne version de WebView Android: Capacitor vérifie android.minWebViewVersion Les appareils qui n'ont jamais mis à jour la vue Web peuvent également échouer sur le JavaScript moderne. plugin de vérificateur de version de WebView peut détecter les WebViews obsolètes et inviter les utilisateurs à mettre à jour.
• Cible de construction trop nouvelle pour le WebView de l'appareil. Réduisez la cible de construction ou ajoutez des polyfills.
• Erreur webDir: vérifie android/app/src/main/assets/public contient index.html.
• Bundle live update endommagé: avec Capgo, un bundle qui ne fait jamais appel notifyAppReady() is automatiquement annulé après le temps d'attente. Consultez les docs de l'actualiseur.

Contenu derrière la barre d'état ou la barre de navigation

Les applications ciblées par SDK 35+ dessinent sur l'écran sur Android 15, et Android 16 a supprimé l'option de dérogation pour les applications ciblées par SDK 36. Capacitor 8 a supprimé adjustMarginsForEdgeToEdge. Gérez les insets avec la configuration du plugin System Bars et le 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);
}

Avec insetsHandling: 'css', Capacitor injecte également --safe-area-inset-* les variables CSS, ce qui aide sur les anciens WebViews où env() rapporte zéro.

Le WebView se recharge lorsqu'il est tourné ou redimensionné

L’activité est recréée. Vérifiez android:configChanges sur l'activité principale inclut density (ajouté à partir de Capacitor 8) avec orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Verrouillage d'orientation ignoré sur les tablettes

Sur Android 16+, les écrans larges ignorent les verrous d'orientation pour les applications ciblant SDK 36. Une opt-out temporaire du manifeste existe (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), mais Android 17 le supprime. Conception pour les deux orientations sur les écrans larges.

Comment déboguer lorsque l'erreur n'est pas listée

1. Lisez le premier erreur. Exécutez ./gradlew assembleDebug --stacktrace et remontez jusqu'à la première FAILURE ou What went wrong.
2. Vérifiez la hiérarchie de dépendances pour les conflits de version : ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtré pour votre package pour les crashes natives. Capacitor logs les appels du plugin avec le Capacitor tag.
4. chrome://inspect pour les erreurs JavaScript.
5. Isoler avec un nouveau bun create @capacitor/app Plus d'outils sont couverts dans le

guide ultime à la débogage des __CAPGO_KEEP_0__ apps ultimate guide to debugging Capacitor apps and comment résoudre les erreurs de build Android dans Capacitor. Si vos machines CI sont le problème plutôt que code, Capgo Build SDK exécute les builds Android avec le JDK approprié et SDK déjà installé.