Capacitor Android 故障排查：常见错误及解决方案

大多数 Capacitor Android 构建失败是由工具链不匹配引起的：错误的 JDK、旧版 Gradle wrapper，或者与依赖项要求的 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 错误，而不是最后一个。

本指南汇总了我们在 Capacitor 项目中最常见的 Android 错误，并按发生环节分组：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 版本对应的预期值：

如果你升级到一半，请按照 如何将您的 Capacitor 应用升级到 Capacitor 8 首先。

Gradle 和 JDK 错误

error: invalid source release: 21

Gradle 运行在 JDK 17 或更低版本，但 @capacitor/android 8 使用 Java 21 编译。在 Android Studio 中： Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK 并选择捆绑的 JDK 21 (JetBrains Runtime)。在命令行和 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 wrapper 版本过旧，无法读取 Java 21 类文件。请更新 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 已更新，但 wrapper 未更新。每个 AGP 版本都有最低 Gradle 版本要求，AGP 8.13 需要 Gradle 8.13+。如上所述，将 wrapper 设置为 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() 位于 repositories，然后使用以下内容重试 --refresh-dependencies。企业网络通常需要镜像源。

Java heap space 或 GC overhead limit exceeded

在 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 标准库 artifact 存在重叠的类，通常是因为某个插件拉入了旧版本 kotlin-stdlib-jdk8。统一 Kotlin 版本。在 kotlin_version = '2.2.20' 根目录中设置 build.gradle （插件通过 rootProject.ext读取），并升级固定使用 Kotlin 1.x 的插件。如有必要，在 android/app/build.gradle:

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

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

中强制使用 BOM。两个插件引入了不同版本的 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"
}

并从其 manifest 中移除 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 {} block 在 Kotlin 2.2 中会报错，因此仍在使用它的插件需要更新或打补丁。

关于……的错误 proguard-android.txt 在使用 AGP 9 时

如果你已经迁移到 AGP 9，那么引用了 getDefaultProguardFile('proguard-android.txt') 会失败。修复方法是 proguard-android-optimize.txt。详情请参阅 修复 Capacitor 插件在 AGP 9 下的构建错误。对于 Capacitor 8 应用，AGP 8.13 仍是经过测试的版本。

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 将布局重命名为 capacitor_bridge_layout_main。请更新你项目中的引用 MainActivity 或自定义 fragment。

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

针对 Android 12+ 的应用必须设置 android:exported 在每个带 intent filter 的 activity、service 和 receiver 上。添加 android:exported="true" (或 false) 到你的 manifest 中。如果该元素来自插件的 manifest，请升级或修补该插件。

安装错误

INSTALL_FAILED_UPDATE_INCOMPATIBLE

已安装了一个 ID 相同但签名密钥不同的应用，通常是 Play Store 的 release build 与你的 debug build 冲突。请先卸载它：

adb uninstall com.example.app

设备未在 Android Studio 中列出，或 adb devices 显示 unauthorized

启用开发者选项和 USB 调试，在手机上接受 RSA 提示，并使用支持数据传输的 USB 线。 adb kill-server && adb start-server 可解决大多数卡住状态。

Play Console：“您的应用不支持 16 KB 内存页大小”

原生 .so 你应用中的库未按 16 KB 对齐。找到包含该库的插件并升级。参见 Android 16 KB 页面大小与 Capacitor 插件.

为 release build 签名

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 。
2. Android Studio 在同步后同步了 Gradle (File > Sync Project with Gradle Files).
3. 插件会出现在 android/capacitor.settings.gradle.
4. 插件版本与您的 Capacitor 主版本一致。Capacitor 7 插件也许能编译，但注册方式不同。
5. 您运行的不是旧版 APK。请卸载并重新安装。

白屏

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

• net::ERR_CLEARTEXT_NOT_PERMITTED 在 live reload 期间：Android 会阻止明文 HTTP。仅限开发环境，请设置 server.cleartext: true 在 Capacitor 配置中，并 server.url 在发布前移除。
• 无法访问开发服务器：将其绑定到 0.0.0.0，请使用局域网 IP，确保手机和电脑在同一网络，或用以下命令转发端口： bunx cap run android --forwardPorts 5173:5173.
• 旧版 Android System WebView：Capacitor 检查 android.minWebViewVersion （默认 60），并在旧版 WebView 上记录错误。从不更新 WebView 的设备也可能在新版 JavaScript 上出错。 WebView 版本检查插件 可以检测过时的 WebView 并提示用户更新。
• 构建目标版本过新 针对设备的 WebView。降低 bundler target 或添加 polyfills。
• 错误 webDir：检查 android/app/src/main/assets/public 包含 index.html.
• 损坏的 live update bundle: 使用 Capgo 时，若 bundle 从未调用 notifyAppReady() 会在超时后自动回滚。请参阅 updater 文档.

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

面向 SDK 35+ 的应用在 Android 15 上会以 edge-to-edge 方式绘制，而 Android 16 移除了面向 SDK 36 的应用的退出选项。Capacitor 8 移除了 adjustMarginsForEdgeToEdge。使用 System Bars 插件配置和 CSS 处理 insets：

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 变量，这对较旧的 WebView 很有帮助，在这些 WebView 中 env() 报告为零。

旋转或调整大小时 WebView 会重新加载

Activity 正在重建。请检查 android:configChanges 在 MainActivity 中包含 density （Capacitor 8 版本新增）以及 orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

平板上方向锁定被忽略

在 Android 16+ 上，targetSdk 为 SDK 36 的应用在大屏设备上会忽略方向锁定。Manifest 提供了临时退出选项（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 按你的包名过滤以查看原生崩溃。Capacitor 记录插件调用时使用以下 Capacitor tag。
4. chrome://inspect 用于排查 JavaScript 错误。
5. 隔离问题 时，用全新的 bun create @capacitor/app 项目，只保留可疑插件。

更多工具请参阅 调试 Capacitor 应用的终极指南 以及 如何解决 Capacitor 中的 Android 构建错误. 如果问题出在 CI 机器而不是 code， Capgo 构建 在已安装正确 JDK 和 SDK 的情况下运行 Android build。