Perbaiki Capacitor Plugin AGP 9 Build Error

Jika build Anda Capacitor Plugin mulai gagal setelah Anda mengupgrade ke Android Gradle Plugin 9 (AGP 9), kemungkinan besar Anda mengalami masalah konfigurasi Gradle yang kritis.

Artikel ini secara spesifik mengarahkan niat pencarian umum seperti:

Capacitor plugin error AGP 9
Plugin Pembangun Android Gradle 9 gagal
proguard-android.txt Tidak ditemukan
AGP 9 getDefaultProguardFile Error
Capacitor build Android gagal setelah AGP diperbarui

Versi singkat:

proguard-android.txt Sekarang tidak lagi menjadi dasar aman untuk merujuk dalam plugin AGP 9.
Ubah ke proguard-android-optimize.txt.
Rebuild dan verifikasi.

Versi panjang juga penting, terutama jika Anda menjaga banyak plugin atau workspace Capacitor yang besar. Dalam artikel ini, kami membahas:

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

Apa itu Android dalam konteks ini?

Android adalah baik sistem operasi maupun ekosistem pembangunan. Ketika Anda mengirimkan aplikasi atau plugin Capacitor pada Android, proyek Anda akan melewati:

Gradle sebagai sistem pembangunan
Plugin Pengembang Android Gradle (AGP) sebagai integrasi Gradle khusus Android.
The Android SDK toolchain untuk pengemasan, pengurangan, pemeriksaan kesalahan, dan menghasilkan .aar, .apk, atau .aab output.

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 garis dasar yang dihapus atau yang sudah tidak digunakan.

Apa itu Capacitor?

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

Aplikasi Capacitor biasanya mencakup:

Layer web (logika bisnis dan antarmuka pengguna Anda)
Aplikasi __CAPGO_KEEP_0__ biasanya mencakup:ios/, android/)
Plugin yang mengungkapkan fitur native ke JavaScript

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

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

Apa itu Capgo?

Capgo provides tools around Capacitor delivery and operations:

Pembaruan Langsung perubahan bundle web
Ekosistem plugin dan paket fitur asli
Alur pembaruan yang ramah CI/CD untuk tim Capacitor

Meskipun dengan pembaruan live, kestabilan build asli Android tidak dapat ditawar. Anda masih memerlukan build Android bersih untuk:

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

Oleh karena itu, perbaikan kompatibilitas AGP 9 sangat penting: mereka menjaga lapisan plugin tetap dapat diandalkan sehingga pipa pengiriman tetap dapat diprediksi.

Why AGP 9 breaks older plugin configs

Banyak template plugin sejarahnya menggunakan:

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

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

Tanda-tanda umum termasuk kesalahan Gradle selama assemble, lint, atau build tahap, sering menunjukkan sumber daya ProGuard baseline yang hilang atau referensi file default yang tidak valid.

Latar belakang cepat: ProGuard, R8, dan file baseline

R8 Penghemat/optimasi modern code dalam pembangunan Android.
proguard-rules.pro adalah aturan pengecualian kustom Anda untuk proyek/plugin.
getDefaultProguardFile(...) injects an Android-provided baseline.

Ketika Anda mengacu pada:

proguard-android.txt -> dasar garis bawah legasi, minimal
proguard-android-optimize.txt -> dasar garis bawah yang dioptimalkan modern (rekomendasi default dalam konfigurasi saat ini)

Untuk konsistensi dengan AGP 9, beralih ke proguard-android-optimize.txt adalah solusi yang praktis.

Solusi satu baris

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
Apapun file generator/template yang membuat konfigurasi Gradle baru untuk plugin

Petunjuk migrasi untuk satu plugin

1. Temukan referensi lama

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

2. Ganti dengan yang baru

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"

Kemudian validasi bahwa tidak ada sumber plugin yang diawasi 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 hasil berarti referensi baseline lama hilang dari file plugin yang diawasi.

Status Capgo peluncuran

We completed this migration across all official Capgo Capacitor plugin repositories and templates:

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

Menghindari jenis kesalahan konversi AGP 9 yang umum sebelum mereka menabrak CI.

Mengapa ini penting bahkan jika build Anda berhasil hari ini

Mungkin Anda tidak melihat gagal segera jika:

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

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

Mengatasi Masalah Jika Bangun Tidak Berhasil Setelah Penggantian

Periksa Poin-Poin Berikut:

Setiap Modul Telah Diperbaiki. Periksa Modul Plugin, Modul Aplikasi, Sampel, dan Sumber Daya Template.
Tidak Ada Referensi Kedua di Skrip Bersama. Cari Seluruh Repositori (Termasuk Skrip Gradle Kustom).
Cache Sudah Bersih. Jalankan ./gradlew clean dan Rebuild.
Versi AGP / Gradle / JDK Sama. Gunakan Kombinasi yang Disediakan Dokumentasi Android untuk Versi AGP Anda.
CI Menggunakan Versi yang Sama dengan Lokal. Tetapkan Versi JDK dan Gradle Wrapper di CI untuk Menghindari Drift Lingkungan.
Anda Tidak Mengganti Hanya node_modules. Perbaiki Sumber Plugin yang Ditracking, Bukan Direktori Ketergantungan Transient.

Mengapa Mengapa Mengatasi Masalah Bangun AGP 9 Capacitor

Mengapa Mengatasi Masalah Bangun `proguard-android.txt` tidak ditemukan di AGP 9?

Ganti:

getDefaultProguardFile('proguard-android.txt')

Dengan:

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

Lalu jalankan kembali dengan membersihkan.

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

Sebagian besar gagalnya berasal dari konfigurasi Gradle legacy di plugin android/build.gradle yang masih mengacu pada proguard-android.txt. 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 pada plugin perwakilan.

Apakah masalah ini hanya Capacitor?

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

Apa kata kunci yang relevan untuk migrasi ini?

Jika Anda mendokumentasikan hal ini di buku petunjuk internal atau halaman dukungan, termasuk istilah seperti:

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

Pengembang Android: Tinjauan build aplikasi Anda
Plugin Pengembang Android: Catatan Rilis
Pengurangan Android code: R8 dan Aturan
Dokumen Gradle: Dasar-Dasar Alat Bangun
Dokumen Capacitor: Dokumentasi Resmi
Dokumen Capgo: Dokumen Auto Update

Kesimpulan Akhir

Masalah ini dengan AGP 9 sederhana, tetapi mudah dilupakan di workspace multi-plugin. Setelah Anda mengganti proguard-android.txt bersama proguard-android-optimize.txt semua bangunan Android menjadi lebih terprediksi kembali.

Jika Anda menggunakan plugin Capgo, migrasi ini sudah diterapkan di repositori resmi sehingga Anda dapat mengupgrade dengan lebih sedikit kejutan.

Teruskan dari Capacitor Plugin AGP 9 Build Error Fix

Jika Anda menggunakan Capacitor Mengatasi Kesalahan Pembangunan Plugin AGP 9 untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo CI/CD untuk alur kerja produk di Capgo CI/CD, Capgo Pembangunan Nadi Asli untuk alur kerja produk di Capgo Native Builds, Capgo Integrasi untuk alur kerja produk di Integrasi Capgo Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan GitHub Actions Integration untuk detail implementasi di GitHub Integrasi Aksi.

Perbaikan Kesalahan Pembangunan Plugin AGP 9 Capacitor