Capacitor Plugin AGP 9 Build Error Fix

Jika Anda memiliki Capacitor plugin mulai gagal setelah mengupgrade ke Android Gradle Plugin 9 (AGP 9), Anda mungkin mengalami masalah konfigurasi Gradle kecil tetapi sangat kritis.

Artikel ini secara spesifik mengarahkan niat pencarian umum seperti:

Capacitor error konfigurasi plugin AGP 9
Plugin AGP 9 gagal membangun
proguard-android.txt tidak ditemukan
AGP 9 getDefaultProguardFile error
Capacitor gagal membangun Android setelah mengupgrade AGP

Versi singkat:

proguard-android.txt tidak lagi merupakan dasar aman default untuk merujuk dalam AGP 9 plugin builds.
Ganti ke proguard-android-optimize.txt.
Rebuild dan verifikasi.

Versi yang lebih panjang juga penting, terutama jika Anda menjaga banyak plugin atau workspace besar Capacitor.

Apa itu Android dan AGP dalam rantai pembangunan?
Apa itu Capacitor dan bagaimana plugin build bekerja?
Apa itu __CAPGO_KEEP_0__? Capgo adalah dan mengapa hal ini penting untuk keandalan rilis. Perubahan AGP 9 yang tepat yang menghancurkan template plugin lama.
Strategi migrasi aman untuk satu repositori atau banyak repositori.
Apa itu Android dalam konteks ini?

Android adalah baik sistem operasi dan ekosistem pembangunan. Ketika Anda mengirimkan aplikasi atau plugin __CAPGO_KEEP_0__ pada Android, proyek Anda melalui:

Gradle is both an operating system and a build ecosystem. When you ship a Capacitor app or plugin on Android, your project goes through:

Apa itu __CAPGO_KEEP_0__ dan bagaimana plugin build bekerja? sebagai sistem pembangunan.
Android Gradle Plugin (AGP) sebagai integrasi Gradle khusus Android.
Alat Android SDK untuk pengemasan, pengurangan, pemeriksaan kesalahan, dan produksi .aar, .apk, atau .aab hasil.

Ketika versi AGP berubah, beberapa default dan file internal juga dapat berubah. Konfigurasi plugin yang berfungsi untuk AGP 8 dapat gagal pada AGP 9 jika mengacu pada basis yang dihapus atau yang sudah tidak digunakan lagi.

Apa itu Capacitor?

Capacitor adalah runtime lintas platform yang memungkinkan Anda membangun aplikasi iOS/Android dengan web code (TypeScript, JavaScript, HTML, CSS) sambil masih mengakses API native.

Capacitor biasanya mencakup:

Layer web (UI dan logika bisnis Anda)
Lingkungan shell asli (ios/, android/)
Plugin yang mengungkapkan fitur native ke JavaScript

Setiap plugin memiliki konfigurasi build native sendiri. Pada Android, ini berarti setiap plugin termasuk android/build.gradle file yang AGP harus memparse dan mengompilasi dengan benar.

Jika pengaturan Gradle plugin sudah ketinggalan zaman, proses build aplikasi seluruhnya bisa gagal, bahkan ketika web code Anda sudah benar.

Apa itu Capgo?

Capgo menawarkan alat seputar pengiriman dan operasi Capacitor:

Pembaruan hidup untuk perubahan bundle web
Ekosistem plugin dan paket fitur native
Pengaturan kerja update yang ramah CI/CD untuk tim Capacitor

Meskipun ada pembaruan langsung, kestabilan pembangunan asli tidak dapat ditawar. Anda masih memerlukan pembangunan Android yang bersih untuk:

Rilis App Store / Play Store
Pembaruan plugin native
Migrasi platform SDK
Pengenalan tim dan keandalan CI

Itulah mengapa perbaikan kompatibilitas AGP 9 penting: mereka menjaga lapisan plugin Anda dapat diandalkan sehingga pipa pengiriman tetap dapat diprediksi.

Mengapa AGP 9 mengganggu konfigurasi plugin yang lebih tua

Banyak template plugin sejarahnya digunakan:

proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

Dalam pengaturan AGP 9, referensi dasar ini dapat gagal karena file yang lama tidak lagi dapat dipastikan ada di lokasi yang diharapkan oleh template/config yang lebih tua.

Gejala umum termasuk kesalahan Gradle selama assemble, lintatau build tahap, sering menunjukkan sumber daya ProGuard dasar yang hilang atau referensi file default yang tidak valid.

Latar belakang cepat: ProGuard, R8, dan file basis

R8 code shrinker/optimizer modern di Android builds.
proguard-rules.pro Apakah aturan pengecualian kustom project/plugin Anda.
getDefaultProguardFile(...) Menginjeksi sebuah basis Android yang disediakan.

Ketika Anda mengacu:

proguard-android.txt -> basis minimal legacy
proguard-android-optimize.txt -> basis basis modern yang dioptimalkan (rekomendasi default dalam pengaturan saat ini)

Untuk konsistensi AGP 9, beralih ke proguard-android-optimize.txt Pemecahan satu baris

Perbarui file Gradle plugin dan modul aplikasi:

Perbarui plugin dan file Gradle modul aplikasi:

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

Setidaknya, periksa:

android/build.gradle di setiap plugin
example-app/android/app/build.gradle di repositori plugin
Berapa file generator/template yang membuat konfigurasi Gradle baru untuk plugin

Petunjuk migrasi untuk satu plugin

1. Cari referensi lama

rg -n "proguard-android\\.txt" android example-app

2. Ganti dengan __CAPGO_KEEP_0__

perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g" \
  android/build.gradle example-app/android/app/build.gradle

3. Verifikasi dengan Bun

bun run verify:android

Jika plugin Anda memiliki skrip verifikasi lengkap, jalankan:

bun run verify

Perbarui semua repositori plugin secara batch

Jika Anda menjaga banyak repositori plugin dalam satu workspace, otomatisasikan:

rg -l "proguard-android\\.txt" capacitor-* \
  --glob '!**/node_modules/**' \
  --glob '!**/.gradle/**' \
  --glob '!**/build/**' \
| xargs perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g"

Lalu validasi bahwa tidak ada sumber plugin yang diikuti masih menggunakan file lama:

for d in capacitor-*; do
  [ -d "$d/.git" ] || continue
  git -C "$d" grep -n "proguard-android\\.txt" -- || true
done

Tidak ada match berarti referensi lama basis lama hilang dari file plugin yang diikuti.

Capgo status peluncuran

Kami telah menyelesaikan migrasi ini di semua repositori dan template resmi Capgo Capacitor:

Modul Android plugin sekarang mengacu pada proguard-android-optimize.txt
Contoh aplikasi Android plugin telah diperbarui juga
Template pengembangan plugin telah diperbarui sehingga plugin baru aman secara default dari AGP 9

Hal ini mencegah jenis kesalahan kelas umum gagal upgrade AGP 9 sebelum mereka menabrak CI

Mengapa ini penting bahkan jika build Anda berhasil hari ini

Anda mungkin tidak melihat gagal segera jika:

Cache CI Anda masih menyembunyikan masalah
Anda memiliki versi AGP campuran di proyek-proyek
Hanya beberapa modul yang dibangun kembali di dev lokal

Tapi akhirnya, bangunan bersih, lingkungan baru, atau pengguna runner yang ditingkatkan mengungkapkannya. Melakukan migrasi sekarang menghilangkan ketidakstabilan yang disembunyikan.

Mengatasi masalah jika bangunan masih gagal setelah penggantian

Periksa poin-poin berikut:

Setiap modul telah diperbaiki. Lihat modul plugin, modul aplikasi, contoh, dan aset template.
Tidak ada referensi kedua di skrip bersama. Cari seluruh repositori (termasuk skrip Gradle kustom).
Cache bersih. Jalankan ./gradlew clean dan bangun ulang.
Versi AGP / Gradle / JDK disesuaikan. Gunakan kombinasi yang didukung oleh dokumentasi Android untuk versi AGP Anda.
CI menggunakan versi yang sama dengan lokal. Tetapkan versi JDK dan wrapper Gradle di CI untuk menghindari pergeseran lingkungan.
Anda tidak hanya memperbaiki node_modules Perbaiki sumber plugin yang dipantau, bukan direktori ketergantungan transien.

FAQ SEO: AGP 9 Capacitor error bangunan plugin

Bagaimana cara memperbaiki `proguard-android.txt` tidak ditemukan di AGP 9?

Ganti:

getDefaultProguardFile('proguard-android.txt')

Dengan:

getDefaultProguardFile('proguard-android-optimize.txt')

Lalu jalankan perbaikan bersih.

Mengapa plugin Capacitor saya gagal dibangun setelah mengupgrade ke Android Gradle Plugin 9?

Kebanyakan gagalnya berasal dari konfigurasi Gradle turunan di plugin android/build.gradle file yang masih mengacu pada proguard-android.txt. Projek AGP 9 harus menggunakan proguard-android-optimize.txt.

Apa jalur migrasi AGP 9 yang paling cepat untuk banyak plugin Capacitor?

Gunakan perintah pencarian dan penggantian workspace-wide, lalu validasi dengan git grep dan jalankan bun run verify:android plugin-plugin-plugin.

Apakah ini hanya masalah Capacitor?

Tidak. Apapun modul Android (aplikasi atau library) yang menggunakan referensi ProGuard yang sudah tidak digunakan lagi dapat mengalami kesalahan AGP 9 saat build. Hal ini sangat terlihat dalam ekosistem plugin karena banyak repository yang menggunakan template lama.

Apa saja kata kunci yang relevan untuk migrasi ini?

Jika Anda mendokumentasikan hal ini di buku catatan internal atau halaman dukungan, termasuklah istilah seperti:

kesalahan build AGP 9
ProGuard file Android Gradle Plugin 9 hilang
Capacitor plugin Android gagal build
proguard-android.txt pengganti
proguard-android-optimize.txt migrasi

Pengembang Android: Ringkasan aplikasi Anda
Android Gradle Plugin: Catatan rilis
Android code pengurangan: R8 dan aturan
Dokumen Gradle: Dasar-dasar alat pembangun
Capacitor dokumen: Dokumentasi resmi
Capgo dokumen: Dokumen auto update

Kesimpulan akhir

Masalah AGP 9 ini sederhana, tetapi mudah dilupakan dalam lingkungan kerja plugin multi. proguard-android.txt Setelah Anda mengganti proguard-android-optimize.txt dengan

If you use Capgo plugins, this migration is already applied in official repositories so you can upgrade with fewer surprises.