Capacitor Mengatasi Masalah Pada Android: Kesalahan Umum dan Solusi

Banyak kesalahan pembangunan Capacitor Android berasal dari kesalahan toolchain: JDK yang salah, wrapper Gradle yang tua, atau level SDK yang tidak sesuai dengan kebutuhan dependency. Untuk Capacitor 8, gunakan JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk dan targetSdk 36 dan minSdk 24, kemudian jalankan bunx cap sync android dan baca kesalahan Gradle pertama, bukan yang terakhir.

Panduan ini menyajikan kesalahan Android yang paling sering kita lihat di proyek Capacitor, yang dikategorikan berdasarkan lokasinya: pengaturan Gradle, penyelesaian dependency, kompilasi, instalasi, dan runtime. Untuk iOS, lihat Capacitor Panduan troubleshooting iOS.

Daftar checklist triage cepat

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

Kemudian konfirmasi nilai yang diharapkan untuk versi Capacitor Anda:

Jika Anda sedang melakukan pembaruan, ikuti Bagaimana Membuat Aplikasi Capacitor Anda Berubah ke Capacitor 8 first.

Error Gradle / JDK

error: invalid source release: 21

Gradle berjalan pada JDK 17 atau lebih lama, tetapi @capacitor/android 8 dapat dikompilasi dengan Java 21. Di Studio Android: Pengaturan > Bangun, Eksekusi, dan Pengiriman > Alat Bangun > Gradle > JDK Gradle dan pilih JDK 21 yang dibundel (Runtime JetBrains). Di command line dan 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

Masalah sebaliknya: Anda menjalankan JDK 21 dengan wrapper Gradle yang terlalu tua untuk membaca file kelas Java 21. Perbarui 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 diperbarui tetapi wrapper tidak. Setiap versi AGP memiliki versi Gradle minimum, dan AGP 8.13 memerlukan Gradle 8.13+. Atur wrapper ke 8.14.3 seperti di atas.

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

Studio Android Anda lebih tua dari AGP di proyek. Pasang Studio Android Otter atau yang lebih baru.

SDK location not found

Gradle tidak dapat menemukan Android SDK. Buka proyek sekali di Studio Android (mengenai file ini) android/local.propertiesatau atur variabel:

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

. Ini berisi jalur spesifik mesin. local.propertiesIt berisi jalur mesin khusus.

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

Masalah jaringan atau repositori. Periksa pengaturan proxy di ~/.gradle/gradle.propertiesdan google() ada di mavenCentral() ada di repositoriesdan coba lagi dengan --refresh-dependenciesJaringan korporat sering memerlukan sebuah replika.

Java heap space atau GC overhead limit exceeded

Naikkan memori Gradle android/gradle.properties:

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

Templat Capacitor ini dikirimkan bersama -Xmx1536myang sangat ketat untuk aplikasi dengan banyak plugin.

Dependency and SDK level errors

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

compileSdkVersion adalah di bawah apa yang dibutuhkan oleh sebuah library AndroidX. Aturlah ke 36 di variables.gradle. If the error names a plugin module, that plugin hardcodes an old value. Upgrade it, or perbaiki build.gradle-nya.

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

atau minSdkVersion Versi Capacitor harus di atas kebutuhan dependency. Capacitor 8 memerlukan 24. Naikkan ke variables.gradle.

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

Dua artefak standard library Kotlin dengan kelas yang berlapis, biasanya karena salah satu plugin menarik versi lama kotlin-stdlib-jdk8Pilih versi Kotlin yang sama. Tetapkan kotlin_version = '2.2.20' di root Anda build.gradle (plugin membacanya melalui rootProject.ext) dan perbarui plugin yang memasang Kotlin 1.x. Jika perlu, paksa BOM di android/app/build.gradle:

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

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

Dua plugin membawa versi berbeda dari Play Services atau Firebase. Sebagian besar Capacitor plugin membaca versi dari variables.gradle Contohnya firebaseMessagingVersionTentukan mereka sekali di sana sehingga setiap plugin menggunakan nilai yang sama.

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

android/capacitor.settings.gradle and android/app/capacitor.build.gradle Versi sudah ketinggalan. Kedua versi ini dibuat. Jalankan bunx cap sync android, then File > Sinkronkan Projek dengan File Gradle.

Masalah Pengekompilan

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

AGP 8+ memerlukan namespace dalam setiap modul Android. Plugin lama hanya mengumumkan package dalam file AndroidManifest.xmlPerbarui plugin. Jika tidak ada rilis, patchnya android/build.gradle:

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

dari manifestnya. package atribut dari manifest-nya.

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

Sebuah modul Kotlin (milik Anda atau plugin) memiliki versi yang berbeda jvmTarget lebih baik daripada Java-nya targetCompatibilityDalam Kotlin 2.x, aturlah compilerOptions:

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

Yang Lama kotlinOptions {} Kotlin 2.2 memiliki masalah, sehingga plugin yang masih menggunakan versi ini memerlukan pembaruan atau patch.

Masalah tentang proguard-android.txt dengan AGP 9

Jika Anda sudah berpindah ke AGP 9, plugin yang mengacu getDefaultProguardFile('proguard-android.txt') Gagal. Solusi adalah proguard-android-optimize.txt. Informasi lengkap dalam perbaiki kesalahan pembangunan plugin Capacitor dengan AGP 9. Untuk aplikasi Capacitor 8, versi AGP 8.13 tetap versi yang telah diuji.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 telah mengubah nama layout menjadi capacitor_bridge_layout_mainPerbarui referensi di fragment Anda MainActivity atau fragment kustom.

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

Aplikasi yang mengarah ke Android 12+ harus mengatur android:exported pada setiap aktivitas, layanan, dan penerima dengan filter intent. Tambahkan android:exported="true" atau falsedalam file manifest Anda. Jika elemen tersebut berasal dari manifest plugin, upgrade atau patch plugin tersebut.

Error Pemasangan

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Sebuah aplikasi dengan ID yang sama tetapi menggunakan kunci tanda tangan yang berbeda telah terpasang, biasanya versi rilis dari Play Store versus versi debug Anda. Hapus terlebih dahulu:

adb uninstall com.example.app

Perangkat tidak terdaftar di Android Studio atau adb devices menampilkan unauthorized

aktifkan Opsi Pengembang dan debugging USB, terima prompt RSA di ponsel, dan gunakan kabel data yang kompatibel. adb kill-server && adb start-server mengatasi kebanyakan keadaan yang terjebak.

Play Console: “Aplikasi Anda tidak mendukung ukuran halaman memori 16 KB”

Sebuah .so library native di aplikasi Anda tidak teralin 16 KB. Cari plugin yang mengirimkannya dan upgrade. Lihat Ukuran Halaman Memori Android 16 KB dan Capacitor plugin.

Menggunakan tanda tangan rilis build

Penyebab keystore yang hilang atau salah Keystore file not found atau Failed to read keyatau Menggunakan tanda tangan rilis build 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.

Error Waktu Eksekusi

"X" plugin is not implemented on android

1. Error waktu runtime package.json and you ran bunx cap sync android dan Anda menjalankan
2. Android Studio synced Gradle after the sync (File > Sinkronkan Projek dengan File Gradle).
3. Plugin ini muncul di android/capacitor.settings.gradle.
4. The plugin version matches your Capacitor major. A Capacitor 7 plugin may compile but register differently.
5. Anda tidak menjalankan APK yang sudah lama. Uninstall dan reinstall.

Tampilan layar putih kosong

Buka chrome://inspect dan periksa konsol WebView. Penyebab umum:

• net::ERR_CLEARTEXT_NOT_PERMITTED selama live reload: Android melarang HTTP biasa. Untuk pengembangan saja, atur server.cleartext: true di konfigurasi Capacitor Anda, dan hapus server.url sebelum rilis.
• Server pengembangan tidak dapat diakses: ikatkan ke 0.0.0.0, gunakan IP LAN Anda, pastikan ponsel dan komputer Anda berada di jaringan yang sama, atau forward port dengan bunx cap run android --forwardPorts 5173:5173.
• Android WebView Lama: Capacitor memeriksa android.minWebViewVersion (default 60) dan mencatat kesalahan pada WebViews yang lebih tua. Perangkat yang tidak pernah memperbarui WebView mungkin juga gagal pada JavaScript modern. The Plugin Pemeriksa Versi WebView Dapat mendeteksi WebView yang usang dan meminta pengguna untuk memperbarui.
• Target Pembangunan Terlalu Baru untuk WebView perangkat. Turunkan target bundler atau tambahkan polifill.
• Salah webDir: periksa android/app/src/main/assets/public mengandung index.html.
• Bundle live update yang Rusak: dengan Capgo, sebuah bundle yang tidak pernah memanggil notifyAppReady() diroll back secara otomatis setelah waktu tunggu. Lihat docs pembaruan.

Isi di balik status bar atau navigation bar

Aplikasi yang mengincar SDK 35+ dapat menampilkan layar penuh di Android 15, dan Android 16 menghilangkan pilihan untuk aplikasi yang mengincar SDK 36. Capacitor 8 telah dihapus. adjustMarginsForEdgeToEdge. Atasi insets dengan plugin konfigurasi System Bars dan 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);
}

Dengan insetsHandling: 'css', Capacitor juga menginjeksi --safe-area-inset-* variabel CSS, yang membantu pada WebViews yang lebih tua di mana env() laporan menunjukkan 0.

WebView reload ketika memutar atau mengubah ukuran

Aktivitas sedang dibuat ulang. Periksa android:configChanges aplikasi utama termasuk density (added in Capacitor 8) along with orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Orientasi lock diabaikan pada tablet

Pada Android 16+, layar besar mengabaikan orientasi lock untuk aplikasi yang mengtarget SDK 36. Ada pilihan opt-out manifest sementara (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), tetapi Android 17 menghilangkannya. Desain untuk kedua orientasi pada layar besar.

Bagaimana mengatasi ketika kesalahan tidak terdaftar

1. Baca kesalahan pertama. Jalankan ./gradlew assembleDebug --stacktrace dan gulirkan ke atas ke bagian pertama FAILURE or What went wrong.
2. Periksa tumpukan dependensi untuk konflik versi: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat diffilter untuk paket Anda untuk crash native. Capacitor log plugin dengan tag Capacitor tag.
4. Chrome://Pengawasan untuk JavaScript error.
5. Isolasi dengan versi terbaru bun create @capacitor/app projek dan hanya plugin yang diduga.

Beberapa alat lainnya dapat ditemukan di bagaimana mengatasi error build Android di Capacitor and how to resolve Android build errors in CapacitorJika mesin CI Anda adalah masalahnya bukan code. Capgo Pembangunan SDK menjalankan pembangunan Android dengan JDK yang tepat dan SDK yang sudah terinstal.