Capacitor Android-Problembehandlung: Häufige Fehler und Lösungen

Die meisten Capacitor Android-Buildfehler resultieren aus einer Werkzeugkette-Mismatch: dem falschen JDK, einem alten Gradle-Wrapper oder einem SDK-Level, das nicht mit dem Bedarf einer Abhängigkeit übereinstimmt. Für Capacitor 8 verwenden Sie JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk und targetSdk 36 und minSdk 24, und führen Sie dann aus bunx cap sync android und lesen Sie die erste Gradle-Fehlermeldung, nicht die letzte.

Dieses Leitfaden listet die häufigsten Android-Fehler auf, die wir in Capacitor-Projekten sehen, gruppiert nach Ort: Gradle-Einrichtung, Abhängigkeitsauflösung, Kompilierung, Installieren und Laufzeit. Für iOS siehe das Capacitor iOS troubleshooting guide.

Schnellüberblickscheckliste

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

Bestätigen Sie dann die erwarteten Werte für Ihre Capacitor Version:

Wenn Sie sich im Upgrade befinden, folgen Sie wie Sie Ihre Capacitor-App auf Capacitor 8 updaten first.

Gradle- und JDK-Fehler

error: invalid source release: 21

8 kompiliert mit Java 21. In Android Studio: @capacitor/android 8 kompiliert mit Java 21. In Android Studio: und wählen Sie das eingebundene JDK 21 (JetBrains Runtime). Auf der Befehlszeile und in CI: und wählen Sie das eingebundene JDK 21 (JetBrains Runtime). Auf der Befehlszeile und 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

Das umgekehrte Problem: Sie führen JDK 21 mit einem zu alten Gradle-Wrapper aus, der Java 21-Klassen nicht lesen kann. Aktualisieren Sie den 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 wurde aktualisiert, aber der Wrapper nicht. Jede AGP-Version hat eine Mindestversion von Gradle, und AGP 8.13 benötigt Gradle 8.13+. Setzen Sie den Wrapper auf 8.14.3 wie oben.

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

Ihr Android Studio ist älter als die AGP im Projekt. Installieren Sie Android Studio Otter oder neuer.

SDK location not found

Gradle kann die Android-Datei nicht finden. SDK. Öffnen Sie das Projekt einmal in Android Studio (es schreibt android/local.properties), oder setzen Sie die Variable:

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

Kommunizieren Sie nicht local.propertiesEs enthält einen maschinen-spezifischen Pfad.

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

Netzwerk- oder Repository-Probleme. Überprüfen Sie die Proxy-Einstellungen in ~/.gradle/gradle.propertiesstellen sicher google() und mavenCentral() sind in repositoriesund versuchen Sie es erneut mit --refresh-dependencies. Corporate Netzwerke benötigen oft einen Spiegel.

Java heap space oder GC overhead limit exceeded

Erhöhen Sie die Gradle-Memory android/gradle.properties:

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

Das Capacitor-Template kommt mit -Xmx1536m, die für Apps mit vielen Plugins eng ist.

Abhängigkeits- und SDK-Level-Fehler

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

compileSdkVersion ist auf AndroidX-Bibliotheken festgelegt. Stellen Sie es auf 36 ein. variables.gradleist unter der Mindestanforderung, die ein AndroidX-Bibliothek benötigt. Setze es auf 36 in patchen seinen build.gradle.

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

Ihr Apps minSdkVersion ist niedriger als ein Abhängigkeit. Capacitor 8 benötigt 24. Erhöhen Sie es auf variables.gradle.

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

Zwei Kotlin-Standardbibliothekskomponenten mit überlappenden Klassen, meistens weil ein Plugin eine alte Version zieht. Aktualisiere die Plugins, oder kotlin-stdlib-jdk8. Stellen Sie sich auf eine Kotlin-Version ein. Set kotlin_version = '2.2.20' in Ihrem Root build.gradle (Plugins lesen es über) rootProject.ext) und aktualisieren Sie Plugins, die Kotlin 1.x festlegen. Wenn nötig, zwingen Sie die BOM in android/app/build.gradle:

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

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

Zwei Plugins bringen unterschiedliche Versionen von Play Services oder Firebase. Die meisten Capacitor Plugins lesen Versionen aus variables.gradle Plugins lesen Versionen aus firebaseMessagingVersion), definieren Sie sie einmal dort, damit jeder Plugin dieselbe Werte verwendet.

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

android/capacitor.settings.gradle and android/app/capacitor.build.gradle sind veraltet. Beide werden generiert. Führen Sie bunx cap sync android, then Datei > Projekt synchronisieren.

Kompilationsfehler

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

AGP 8+ erfordert namespace jedes Android-Modul. Alte Plugins deklarieren package nur in ihrem AndroidManifest.xml. Aktualisiere das Plugin. Wenn keine Release-Version existiert, patche es. android/build.gradle:

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

Attribut aus seinem Manifest. package Attribut aus seinem Manifest.

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

Ein Kotlin-Modul (deines oder eines Plugins) hat eine andere jvmTarget mehr als sein Java targetCompatibilityIn Kotlin 2.x, setzen Sie es mit compilerOptions:

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

Die alte kotlinOptions {} Ein Block ist ein Fehler in Kotlin 2.2, daher benötigen Plugins, die ihn noch verwenden, eine Aktualisierung oder ein Patch.

Fehler über proguard-android.txt Fehler mit AGP 9

Wenn Sie bereits zu AGP 9 gewechselt haben, beziehen sich Plugins, die getDefaultProguardFile('proguard-android.txt') Fehler. Die Lösung ist proguard-android-optimize.txt. Weitere Informationen finden Sie in fixen Sie Capacitor-Plugin-Fehler mit AGP 9. Für Capacitor-Apps, die auf 8 laufen, bleibt AGP 8.13 die getestete Version.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 hat die Layout-Datei umbenannt in capacitor_bridge_layout_main. Aktualisieren Sie die Referenz in Ihrem MainActivity oder Fragment.

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

Apps, die auf Android 12+ zielen, müssen } android:exported auf jeder Aktivität, Dienst und Empfänger mit einem Intent-Filter. android:exported="true" (oder falsein Ihrem Manifest. Wenn das Element aus einem Plugin-Manifest stammt, aktualisieren oder patchen Sie das Plugin.

Installationsfehler

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Ein App mit demselben ID, aber einem anderen Signatur-Schlüssel ist installiert, meist ein Release-Build aus dem Google Play Store gegenüber Ihrem Debug-Build. Entfernen Sie es zuerst:

adb uninstall com.example.app

Das Gerät wird nicht in Android Studio oder adb devices zeigt unauthorized

Aktivieren Sie die Entwickleroptionen und USB-Debugging, akzeptieren Sie den RSA-Prompt auf dem Telefon und verwenden Sie einen Daten-fähigen Kabel. adb kill-server && adb start-server behebt die meisten blockierten Zustände.

Google Play Console: „Ihre App unterstützt keine 16 KB-Speicherseiten“

Ein native .so Bibliothek in Ihrer App ist nicht auf 16 KB ausgerichtet. Finden Sie das Plugin, das sie liefert, und aktualisieren Sie. Android 16 KB-Seitengröße und Capacitor-Plugins.

Ein Releasebuild signieren

Fehlen oder falsche Keystore-Einstellungen verursachen Keystore file not found oder Failed to read key. Our Fehler bei der Ausführung 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.

Laufzeitfehler

"X" plugin is not implemented on android

1. Der Plugin ist in package.json and you ran bunx cap sync android Alternativen oder
2. Android Studio hat nach dem Sync das Gradle synchronisiert.Datei > Projekt synchronisieren).
3. Der Plugin erscheint in android/capacitor.settings.gradle.
4. Die Plugin-Version entspricht Ihrem Capacitor Hauptversion. Ein Capacitor 7 Plugin mag kompilieren, aber anders registrieren.
5. Entfernen Sie die alte APK. Entfernen und erneut installieren.

Leeres weißes Bildschirmfenster

Öffnen chrome://inspect und überprüfen Sie die WebView-Konsole. Häufige Ursachen:

• net::ERR_CLEARTEXT_NOT_PERMITTED während Live-Neuaufladen: Android blockiert einfaches HTTP. Für den Entwicklungsmodus setzen Sie server.cleartext: true in der Capacitor-Konfiguration und entfernen Sie server.url vor der Veröffentlichung.
• Entwicklungs-Server nicht erreichbar: Binden Sie es an 0.0.0.0, verwenden Sie Ihre LAN-IP, halten Sie Telefon und Computer auf demselben Netzwerk oder forwarden Sie den Port mit bunx cap run android --forwardPorts 5173:5173.
• Alte Android System WebView: Capacitor überprüft android.minWebViewVersion (Standard 60) und meldet einen Fehler bei älteren WebViews. Geräte, die das WebView nie aktualisieren, können auch bei modernem JavaScript scheitern. Das WebView-Versionen-Überprüfung-Plugin kann veraltete WebViews erkennen und Benutzer auffordern, zu aktualisieren.
• Buildziel zu neu für das Geräte-WebView. Senken Sie den Zielwert Ihres Bundlers oder fügen Sie Polyfill hinzu.
• Falsch webDir: überprüfen android/app/src/main/assets/public enthält index.html.
• Zerbrochener live update-Bundle: mit Capgo, einem Bundle, das nie Capgo aufruft notifyAppReady() wird automatisch zurückgerollt, sobald der Zeitlimit überschritten ist. Siehe die Dokumentation des Updaters.

Inhalt hinter dem Statusleisten oder Navigationsleisten

Apps, die sich auf SDK 35+ richten, zeichnen sich auf Android 15 und Android 16 ohne Opt-out aus, und Android 16 entfernte das Opt-out für Apps, die sich auf SDK 36 richten. Capacitor 8 entfernte. adjustMarginsForEdgeToEdgeHandle Insets mit der System Bars Plugin-Konfiguration und 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);
}

Mit insetsHandling: 'css', Capacitor injiziert auch --safe-area-inset-* CSS-Variablen, die bei älteren WebViews hilft, wo env() meldet Null.

Die Aktivität wird neu erstellt. Überprüfen Sie

ob die Hauptaktivität enthält android:configChanges auf der Hauptaktivität density (hinzugefügt in Capacitor 8) zusammen mit orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Orientierungssperre ignoriert auf Tablets

Auf Android 16+, große Bildschirme ignorieren die Orientierungssperren für Apps, die sich auf SDK 36 richten. Ein temporärer Manifest-Ausnahmeeintrag besteht ("android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITYWie man debuggt, wenn der Fehler nicht aufgeführt wird

Lesen Sie die erste Fehlermeldung

1. Lese die erste Fehlermeldung. Run ./gradlew assembleDebug --stacktrace scrollen Sie nach oben bis zum ersten FAILURE or What went wrong.
2. für Versionskonflikte: für Versionskonflikte: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat gefiltert auf Ihre Pakete für native Crashs. Capacitor Protokolle Pluginaufrufe mit dem Capacitor Schlagwort.
4. chrome://inspektor für JavaScript-Fehler.
5. Isolieren mit einer frischen bun create @capacitor/app Projekt und nur dem verdächtigen Plugin.

Mehr Werkzeuge werden in der ultimativen Anleitung zum Debuggen von Capacitor Apps und Wie man Android-Buildfehler in Capacitor behebtWenn Ihre CI-Maschinen das Problem sind und nicht der code. Capgo Build mit der richtigen JDK und SDK bereits installiert