Capacitor 安卓故障排除: 常见错误和修复

大多数Capacitor Android 构建失败来自工具链不匹配：错误的 JDK、旧的 Gradle 包装器或SDK级别不符合依赖项所需的级别。对于Capacitor 8，使用 JDK 21、Android Gradle Plugin 8.13.0、Gradle 8.14.3、compileSdk 和 targetSdk 36 和 minSdk 24，然后运行 bunx cap sync android 并阅读第一个 Gradle 错误，而不是最后一个。

本指南列出了 Android 错误，我们在Capacitor 项目中看到最多的，根据它们发生的位置分组：Gradle 配置、依赖解析、编译、安装和运行。对于 iOS，请参见 Capacitor iOS调试指南.

快速排查清单

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

然后确认您的Capacitor版本的预期值:

如果您正在进行升级，请遵循 How to Upgrade Your Capacitor App to Capacitor 8 首先。

Gradle 和 JDK 错误

error: invalid source release: 21

Gradle 运行在 JDK 17 或更早版本，但 @capacitor/android 8 使用 Java 21。 在 Android Studio 中： 设置 > 构建，执行和部署 > 构建工具 > Gradle > Gradle JDK 选择内置 JDK 21（JetBrains 运行时）。 在命令行和 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

你遇到的问题：你使用的JDK 21版本的Gradle包装器太旧，无法读取Java 21类文件。更新包装器：

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已经更新，但包装器没有。每个AGP版本都有一个最低的Gradle版本，AGP 8.13需要Gradle 8.13+。将包装器设置为8.14.3，如上所示。

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

你的Android Studio版本比项目中的AGP版本还要老。安装Android Studio Otter或更高版本。

SDK location not found

Gradle找不到Android SDK。打开项目一次在Android Studio（它会写入 android/local.properties）、或设置变量：

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

不要提交 local.properties。它包含一个机器特定的路径。

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

网络或仓库问题。检查 ~/.gradle/gradle.properties，确保 google() 和 mavenCentral() context repositories在中，确保 --refresh-dependencies企业网络通常需要一个镜像。

Java heap space 或 GC overhead limit exceeded

升高Gradle的内存在 android/gradle.properties:

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

该模板Capacitor与 -Xmx1536m，对于有很多插件的应用来说，这个值太小了。

依赖和SDK级别错误

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

compileSdkVersion 比一个AndroidX库需要的值要低。将其设置为36在 variables.gradle如果错误名称一个插件模块，那么这个插件硬编码了一个旧的值。升级它，或 修复其build.gradle.

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

您的应用的 minSdkVersion 比一个依赖项的值要低。Capacitor 8需要24。升高它在 variables.gradle.

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

两个Kotlin标准库的艺术品有重叠的类，通常是因为一个插件拉取了一个旧的 kotlin-stdlib-jdk8 . Kotlin 版本统一。设置 kotlin_version = '2.2.20' 在根目录（插件通过读取它来获取信息） build.gradle （例如 rootProject.ext）并升级那些锁定 Kotlin 1.x 的插件。如果需要，强制 BOM 在 android/app/build.gradle:

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

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

两个插件提供不同的 Play Services 或 Firebase 版本。多数 Capacitor 插件从 variables.gradle （例如 firebaseMessagingVersion）读取版本，所以在那里定义它们一次，以便每个插件都使用相同的值。

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

android/capacitor.settings.gradle 并 android/app/capacitor.build.gradle 是过时的。它们都是自动生成的。运行 bunx cap sync android，然后 File > Sync Project with Gradle Files.

编译错误

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

AGP 8+ 需要 namespace 在每个 Android 模块中。旧的插件只声明 package 在其 AndroidManifest.xml中。升级插件。如果没有发布版本，则修复其 android/build.gradle:

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

并从其清单中删除 package 属性。

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

一个 Kotlin 模块（你的或插件的）有一个不同的 jvmTarget 与其 Java targetCompatibility。在 Kotlin 2.x 中，使用 compilerOptions:

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

来设置它。 kotlinOptions {} 旧的

关于错误 proguard-android.txt 与 AGP 9

如果您已经升级到 AGP 9，引用 AGP 9 的插件将会 getDefaultProguardFile('proguard-android.txt') 解决方案是 proguard-android-optimize.txt. 详情请参见 修复 AGP 9 中的 Capacitor 插件构建错误. 对于 Capacitor 8 应用，AGP 8.13 仍然是测试版本。

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 重命名了布局为 capacitor_bridge_layout_main。更新您的 MainActivity 或自定义片段中的引用。

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

针对 Android 12+ 的应用必须在每个活动、服务和接收器中设置 android:exported ，并在每个具有意图过滤器的活动、服务和接收器中添加 android:exported="true" （或 falsecontext

targetLanguage

INSTALL_FAILED_UPDATE_INCOMPATIBLE

pagePath

adb uninstall com.example.app

protectedTokens adb devices items unauthorized

text adb kill-server && adb start-server context

text

text .so text 安卓16KB页面大小和Capacitor插件.

签署发布构建

缺失或错误的keystore设置导致 Keystore file not found 或 Failed to read key.我们的 Android keystore生成器 创建keystore和Gradle签名配置。将keystore保存在git外并备份。丢失它意味着您无法更新应用程序，除非使用Play App Signing。

运行时错误

"X" plugin is not implemented on android

1. 插件位于 package.json 并且您已安装它后运行 bunx cap sync android Android Studio已同步Gradle后执行（
2. 文件>同步项目到Gradle文件签署发布构建).
3. 该插件在 android/capacitor.settings.gradle.
4. 该插件版本与您的Capacitor主版本匹配。一个Capacitor 7插件可能会编译但注册方式不同。
5. 您不是在运行一个旧的APK。卸载并重新安装。

白屏

打开 chrome://inspect 并检查WebView控制台。常见原因:

• net::ERR_CLEARTEXT_NOT_PERMITTED 在实时重载期间：Android阻止普通HTTP。仅用于开发，请在__CAPGO_KEEP_0__配置中设置 server.cleartext: true 在Capacitor配置中，移除 server.url 开发服务器无法访问
• :将其绑定到,使用您的局域网IP，确保手机和电脑在同一网络上，或者使用端口转发 0.0.0.0使用你的局域网 IP，确保手机和电脑在同一网络中，或者使用端口转发。 bunx cap run android --forwardPorts 5173:5173.
• 旧版Android系统浏览器: Capacitor 检查 android.minWebViewVersion (默认 60) 并在旧版浏览器上记录错误。可能会在未更新浏览器的设备上失败的现代 JavaScript。 浏览器版本检查插件 可以检测旧版浏览器并提示用户更新。
• 设备的浏览器版本太新 降低打包器目标或添加 polyfills。
• 错误 webDir: 检查 android/app/src/main/assets/public 包含 index.html.
• 错误的 live update 打包: 包含 Capgo, 从未调用 notifyAppReady() 会自动回滚超时后。参见 更新器文档.

状态栏或导航栏后面的内容

目标版本SDK 35+的应用程序在Android 15上绘制边缘到边缘，Android 16移除了目标版本SDK 36的应用程序的优惠券。Capacitor 8移除了 adjustMarginsForEdgeToEdge. 使用系统栏插件配置和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);
}

在 insetsHandling: 'css'，Capacitor也注入 --safe-area-inset-* CSS变量，这在较旧的WebViews中有所帮助，其中 env() 报告零。

当旋转或调整大小时，Web视图会重新加载。

活动正在被重建。检查 android:configChanges 主活动包含 density (在 Capacitor 8 中添加) 一并 orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

平板电脑屏幕方向锁定被忽略

在 Android 16+ 上，屏幕尺寸较大的设备会忽略针对 SDK 36 的应用程序的方向锁定设置。android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), 但 Android 17 移除了它。 设计大屏幕的双向布局。

如何调试未列出的错误

1. 阅读第一个错误。 运行 ./gradlew assembleDebug --stacktrace 向上滚动到第一个 FAILURE 或 What went wrong.
2. 检查依赖树 针对版本冲突： ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat 针对native崩溃过滤到您的包中。 Capacitor 日志插件调用与 Capacitor 标签。
4. Chrome://检查 用于JavaScript错误。
5. 隔离 使用一个新的 bun create @capacitor/app 项目并仅包含可疑插件。

更多工具在 ultimate debugging __CAPGO_KEEP_0__ 应用程序指南中 ultimate guide to debugging Capacitor apps and . 如果您的CI机器是问题，而不是 Capacitor如果您的CI机器是问题的原因，而不是code Capgo 构建 SDK 使用正确的 JDK 运行 Android 构建，并且 SDK 已经安装。