Capacitor Solución de problemas de Android: Errores comunes y soluciones

La mayoría de los errores de compilación de Capacitor Android provienen de una incompatibilidad de herramientas: JDK incorrecto, un wrapper de Gradle antiguo o un nivel SDK que no coincide con lo que una dependencia necesita. Para Capacitor 8, utilice JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk y targetSdk 36 y minSdk 24, y luego ejecute bunx cap sync android y lea el primer error de Gradle, no el último.

Esta guía enumera los errores de Android que vemos más comúnmente en proyectos de Capacitor, agrupados por dónde ocurren: configuración de Gradle, resolución de dependencias, compilación, instalación y ejecución. Para iOS, consulte el Guía de depuración de iOS Capacitor.

Lista de verificación rápida

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

Confirme luego los valores esperados para su versión de Capacitor:

Si estás en medio de una actualización, sigue Cómo actualizar tu aplicación Capacitor a Capacitor 8 primero.

Errores de Gradle y JDK

error: invalid source release: 21

Gradle se ejecuta en JDK 17 o anterior, pero @capacitor/android 8 compila con Java 21. En Android Studio: Configuración > Construcción, ejecución y depuración > Herramientas de construcción > Gradle > JDK de Gradle y selecciona el JDK 21 incorporado (Runtime de JetBrains). En la línea de comandos y en 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 reverse problem: you run JDK 21 with a Gradle wrapper too old to read Java 21 class files. Actualice el 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 se actualizó pero el wrapper no lo hizo. Cada versión de AGP tiene una versión mínima de Gradle, y AGP 8.13 necesita Gradle 8.13+. Establezca el wrapper en 8.14.3 como se indica arriba.

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

Su Android Studio es más antiguo que el AGP del proyecto. Instale Android Studio Otter o una versión más reciente.

SDK location not found

Gradle no puede encontrar el Android SDK. Abra el proyecto una vez en Android Studio (escribe android/local.properties) o establezca la variable:

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

No cometa local.properties. Contiene una ruta específica de la máquina.

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

Problema de red o repositorio. Verifique los ajustes de proxy en ~/.gradle/gradle.propertiesasegúrese google() y mavenCentral() están en repositoriesy vuelve a intentarlo --refresh-dependenciesLas redes corporativas a menudo necesitan un espejo.

Java heap space o GC overhead limit exceeded

o los plugins de Appflow. android/gradle.properties:

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

El template Capacitor se envía con -Xmx1536mque es estrecho para aplicaciones con muchos plugins.

Los errores de dependencia y nivel SDK

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

compileSdkVersion es inferior a lo que necesita una biblioteca AndroidX. Establezca a 36 en variables.gradleSi el nombre del error menciona un módulo de plugin, ese plugin codifica un valor antiguo. Actualícelo, o actualice su archivo build.gradle.

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

Su aplicación minSdkVersion es inferior a la de una dependencia. Capacitor 8 necesita 24. Aumente en variables.gradle.

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

Los dos artefactos de la biblioteca estándar de Kotlin con clases superpuestas, generalmente debido a que un plugin extrae una versión antigua. kotlin-stdlib-jdk8. Alíguense en una versión de Kotlin. Establezca kotlin_version = '2.2.20' en su raíz build.gradle (plugins lo leen a través de) rootProject.ext) y actualice los plugins que pinen Kotlin 1.x. Si es necesario, fuerce el BOM en android/app/build.gradle:

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

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

Dos plugins traen diferentes versiones de Play Services o Firebase. La mayoría de los Capacitor plugins leen versiones de variables.gradle por ejemplo firebaseMessagingVersion), asígnelos una vez allí para que cada plugin utilice el mismo valor.

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

android/capacitor.settings.gradle and android/app/capacitor.build.gradle Los son actualizados. Ambos se generan. Ejecuta bunx cap sync android, then Archivo > Sincronizar proyecto con archivos Gradle.

Errores de compilación

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

AGP 8+ requiere namespace en cada módulo de Android. Los plugins antiguos solo declaran package en su AndroidManifest.xmlUpgrade. Si no existe una versión de lanzamiento, parchea su android/build.gradle:

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

y elimina la package atributo de su manifiesto.

'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 módulo de Kotlin (tuyo o de un plugin) tiene un jvmTarget diferente a su targetCompatibilityEn Kotlin 2.x, establezca con compilerOptions:

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

El viejo kotlinOptions {} El bloque es un error en Kotlin 2.2, por lo que los plugins que aún lo utilizan necesitan una actualización o una corrección.

Errores sobre proguard-android.txt con AGP 9

Si ya se ha movido a AGP 9, los plugins que se refieren getDefaultProguardFile('proguard-android.txt') fallan. La solución es proguard-android-optimize.txt. Detalles completos en solucionar errores de compilación del plugin Capacitor con AGP 9. Para aplicaciones Capacitor 8, AGP 8.13 sigue siendo la versión probada.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 renombró la disposición a capacitor_bridge_layout_mainActualice la referencia en su MainActivity o fragmento personalizado.

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

Apps targeting Android 12+ must set android:exported en cada actividad, servicio y receptor con un filtro de intención. Agregue android:exported="true" (o falseen el archivo manifest. Si el elemento proviene de un archivo manifest de plugin, actualice o parchee el plugin.

Errores de instalación

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Una aplicación con el mismo ID pero con una clave de firma diferente está instalada, generalmente una versión de lanzamiento desde la tienda Play versus su versión de depuración. Desinstálela primero:

adb uninstall com.example.app

No se muestra el dispositivo en Android Studio o adb devices muestra unauthorized

Habilite las opciones de desarrollador y depuración USB, acepte la solicitud RSA en el teléfono y utilice un cable con capacidad de datos. adb kill-server && adb start-server soluciona la mayoría de los estados bloqueados.

Consola de Play: “Su aplicación no admite tamaños de página de memoria de 16 KB”

Un nativo .so La biblioteca en tu aplicación no está alineada en 16 KB. Encuentra el plugin que la envía y actualiza. Ver Android 16 KB de página tamaño y plugins Capacitor.

Firmar un paquete de liberación

Configuración de keystore incorrecta o faltante Keystore file not found o Failed to read keyNuestra Generador de keystore de Android crea un keystore y la configuración de firma de Gradle. Mantenga el keystore fuera de Git y realice una copia de seguridad. Perderlo significa que no podrá actualizar la aplicación a menos que utilice la firma de Play Store.

Errores de tiempo de ejecución

"X" plugin is not implemented on android

1. El plugin está en package.json y ejecutó bunx cap sync android después de instalarlo.
2. Android Studio sincronizó Gradle después de la sincronización ("Archivo > Sincronizar proyecto con archivos Gradle).
3. El plugin aparece en android/capacitor.settings.gradle.
4. La versión del plugin coincide con tu Capacitor mayor. Un plugin Capacitor 7 puede compilar pero registrarse de manera diferente.
5. No estás ejecutando una APK antigua. Desinstala y reinstala.

Pantalla en blanco vacía

Abre chrome://inspect y verifica el consola del WebView. Causas comunes:

• net::ERR_CLEARTEXT_NOT_PERMITTED durante la recarga en vivo: Android bloquea HTTP plano. Para desarrollo solo, establece server.cleartext: true en la configuración de Capacitor y elimina server.url antes de la publicación.
• Servidor de desarrollo inalcanzable: asócialo a 0.0.0.0Utilice su IP de red local, mantenga su teléfono y computadora en la misma red, o redirija el puerto con bunx cap run android --forwardPorts 5173:5173.
• Android WebView antiguo: Capacitor verifica android.minWebViewVersion (por defecto 60) y registra un error en WebViews más antiguos. Los dispositivos que nunca actualizan el WebView también pueden fallar en JavaScript moderno. El plugin de verificador de versión de WebView puede detectar WebViews obsoletos y solicitar a los usuarios que actualicen.
• Objetivo de compilación demasiado nuevo para el WebView del dispositivo. Disminuya el objetivo de compilación o agregue polyfills.
• Wrong webDir: comprueba android/app/src/main/assets/public contiene index.html.
• Bundle live update roto: con Capgo, un paquete que nunca llama notifyAppReady() se deshace automáticamente después del tiempo de espera. Consulte los documentos del actualizador.

Contenido detrás de la barra de estado o de navegación

Aplicaciones que se dirigen a SDK 35+ dibujan de borde a borde en Android 15, y Android 16 eliminó la opción de exención para aplicaciones que se dirigen a SDK 36. Capacitor 8 eliminó adjustMarginsForEdgeToEdgeManeja los insets con la configuración del plugin System Bars y 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 también inyecta --safe-area-inset-* variables de CSS, que ayuda en WebViews más antiguas donde env() informa cero.

La ventana de navegación se recarga al rotar o redimensionar.

La actividad se está recreando. Verifique android:configChanges que la actividad principal incluye density (agregado en Capacitor 8) junto con orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Ignorar el bloqueo de orientación en tabletas

En Android 16+, las pantallas grandes ignoran los bloqueos de orientación para aplicaciones que targetean SDK 36. Existe una opción de manifest temporal de exclusión (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY) pero Android 17 la elimina. Diseñe para ambas orientaciones en pantallas grandes.

Cómo depurar cuando el error no está listado

1. Lee el primer error. Ejecuta ./gradlew assembleDebug --stacktrace y desplázate hacia arriba hasta el primero FAILURE or What went wrong.
2. Verifique el árbol de dependencias para conflictos de versión: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtrado a tu paquete para errores de aplicaciones nativas. Capacitor registros llamadas al plugin con el Capacitor etiqueta.
4. chrome://inspeccionar para errores de JavaScript.
5. Aislado con una instalación nueva bun create @capacitor/app Mas herramientas se cubren en la

guía definitiva para depurar __CAPGO_KEEP_0__ aplicaciones ultimate guide to debugging Capacitor apps and cómo resolver errores de compilación de Android en Capacitor. Si tus máquinas de CI son el problema en lugar de code, Capgo Construcción ejecuta construcciones de Android con el JDK adecuado y SDK ya instalado.