Persiapan untuk Capacitor 9: Apa yang Tim Aplikasi dan Plugin Bisa Lakukan Sekarang

Capacitor 9 is available on the next dist-tag saat ini sedang dalam tahap pengembangan alpha dan akan bergerak menuju ketersediaan umum. Anda tidak perlu mengupgrade aplikasi Anda pada hari alpha dirilis, tetapi official Capacitor 9 update guide dan Petunjuk Pembaruan Plugin sudah menjelaskan perangkat lunak yang terkait dengan lantai dan penghapusan API yang perlu ditangani sejak awal.

Artikel ini adalah Persiapan Daftar Periksa: pekerjaan yang dapat Anda lakukan pada Capacitor 8 (atau pada cabang) sehingga versi akhir bunx cap migrate Alih ke lebih menarik daripada menyakitkan. Ketika Anda siap untuk memindahkan, ikuti panduan Ionic di atas baris demi baris.

Alat dan lantai platform (aplikasi)

Rencanakan CI, mesin lokal, dan pipa penyimpanan Anda sekitar minimum ini:

Jika Anda masih menggunakan Capacitor 8.4 atau lebih awal untuk iOS, Anda juga memerlukan siklus kehidupan UI Scene kerja dari pembaruan Capacitor 8.5 sebelum Cap 9 — Xcode 27 mengharapkannya. Aplikasi yang sudah menggunakan 8.5 dapat melewatkan langkah tambahan itu.

Pada iOS, Swift 6 (dengan Xcode 27) menolak @UIApplicationMain; ketika Anda mengupgrade, gantilah dengan @main in AppDelegate.swift seperti yang dijelaskan dalam panduan resmi.

Cordova pada waktu sinkronisasi aplikasi (bukan langkah persiapan plugin)

Dalam Capacitor 9, layer kompatibilitas Cordova mendeteksi plugin Cordova yang terinstal cap sync mendeteksi plugin Cordova yang terinstalAndroid menghilangkan modul Gradle tambahan ketika tidak ada; iOS menghentikan penambahan CapacitorCordova ke menu Podfile atau Package.swift ketika tidak ada yang ada.

itu adalah app-level behavior change after you upgrade. While you are still on Cap 8, you do not need to rip Cordova out of your template preemptively. Do audit whether any custom native code (yours or a forked plugin) imports Cordova symbols without an actual Cordova plugin in the project — those references will fail once optional Cordova wiring applies.

Android: gradle.properties dan AGP 9 default

Asisten Upgrade AGP sering menulis gradle.properties flags sehingga build tetap menjalankan perilaku AGP 8. Capacitor 9 aplikasi harus remove masukkan entri tersebut daripada membawa mereka maju: kebanyakan sudah usang sebelum AGP 10, dan beberapa mengganggu Cap 9 (misalnya android.builtInKotlin=false menghilangkan dukungan Kotlin yang dibundel oleh AGP 9, dan android.sdk.defaultTargetSdkToCompileSdkIfUnset=false menghentikan AGP dari menginferrasi targetSdkVersion).

Saat Anda melakukan migrasi, juga harapkan untuk:

• Meningkatkan variables.gradle minimum (compile/target SDK 37, minSdkVersion 26, versi AndroidX yang diperbarui — lihat dokumen resmi).
• Menghapus ekspresi targetSdkVersion yang ada di aplikasi build.gradle sehingga AGP 9 dapat menginferrasi dari compileSdkVersion.
• Menyatakan variables.gradle simbol-simbol di bagian atas app/build.gradle (Gradle 9.6 menghentikan pencarian implisit dari proyek root).
• Ubah nama file ProGuard bawaan, migrasikan core-ktx ke androidx.core:core 1.19.0+, menghentikan penggunaan plugin Gradle Kotlin berdiri sendiri, dan menghapus jcenter().

Anda dapat membaca perbedaan hunks di Anda dapat membaca perbedaan hunks dalam: Bagian Android dan terapkan perbaikan yang sama pada cabang sebelum meningkatkan versi Capacitor.

CLI: cap run --url

Capacitor 9 merges live-reload host/port/https flags into a single --url Alih argument. Sebaliknya:

bunx cap run android -l --host 192.168.1.181 --port 5173

Passkan URL server dev Anda cetak:

bunx cap run android --url http://192.168.1.181:5173/

Perbarui skrip update dan snippet README sekarang agar otot otot tidak bertolak belakang dengan CLI baru setelah upgrade.

Plugin resmi: kejutan push dan splash

Perubahan dua yang terlihat oleh pengguna sering muncul di aplikasi produksi:

Pemberitahuan Push (iOS): Dikembalikan alert Opsi presentasi dihapus. Gunakan banner atau list Screen Splash (Android):

Layar Splash (Android): berubah dari launchFadeOutDuration 200 ms ke 0 200 ms hingga 0Jika Anda bergantung pada efek transisi untuk menyembunyikan kegagalan pertama peta, launchFadeOutDuration: 200 secara eksplisit di capacitor.config hingga Anda menyesuaikan UI awal Anda.

Periksa bagian plugin di halaman panduan pembaruan 9.0 untuk versi AndroidX dan Google Play Services yang terkait dengan plugin resmi yang Anda gunakan.

Para pengembang plugin: siapkan pada Cap 8 tanpa mengganggu Cap 8

Jika Anda mengirimkan Capacitor plugin yang dikonsumsi pada Capacitor 8 dan Siapkan Cap 9-ready code, fokus pada ingin Cap 9-ready API, fokus padapenghapusan __CAPGO_KEEP_0__ yang sudah tidak digunakan

, bukan pada perubahan pengemasan Cap-9 saja.

• Ganti @NativePlugin dengan @CapacitorPlugin dan migrasikan API izin / hasil kegiatan yang sudah usang ke @PermissionCallback / @ActivityCallback pola (lihat tabel panduan plugin 9.0 )
• Hapus PluginCall.hasOption, Plugin.getConfigValue, old CapConfig konstruktor dan getter, PluginCall.save() / isSaved()dan penghapusan Java lainnya yang terdaftar di bawah “Perubahan yang Menghancurkan dalam code.”
• Hentikan penggunaan CAPBridge kelas kompatibilitas dan yang sudah tidak digunakan CAPBridgeProtocol bantuan; gunakan ApplicationDelegateProxy, ditulis PluginCall aksesor dan properti bridge dari tabel migrasi.
• Jalankan bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

Jangan menghapus Cordova Produk SPM dari plugin Anda Package.swift Saat Anda masih mendukung Capacitor 8. Projek Cap 8 mengharapkan ketergantungan tersebut ketika plugin Anda berbasis SPM; menghilangkannya terlalu cepat akan mengganggu pengguna yang masih menggunakan 8. optional Cordova / removing the unconditional Cordova product sebagai Capacitor 9-saja garis besar perilisan (atau semver mayor yang secara eksplisit dokumentasi sebagai Cap 9+), setelah Anda berhenti mendukung Cap 8 — seperti yang dijelaskan dalam panduan plugin, bukan sebagai persiapan kerja pada garis Cap 8.

Aturan yang sama berlaku untuk meningkatkan capacitor-swift-pm ke 9.0.0-alpha.x in Package.swiftFungsinya yang seharusnya ada di Cap 9 utama, bukan pada rilis yang kompatibel dengan Cap-8.

Capgo pembaruan hidup dan pembangunan toko Cap 9 asli

Capgo Live Update dan pembangunan toko native Cap 9 bundle web Perbarui secara nirkabel; antarmuka asli masih berasal dari App Store dan Google Play. Ketika Anda memindahkan aplikasi ke Capacitor 9:

1. Ship Riliskanlah (Ship) juga di setidaknya satu toko aplikasi terkompile terhadap Capacitor 9 proyek native (iOS dan Android). Binary tersebut menentukan dasar native Capgo saluran target.
2. Hanya setelah build tersebut ada di tangan pengguna, Anda dapat bergantung pada OTA bundle yang telah diuji terhadap Cap 9 WebView dan perilaku plugin.
3. Tetapkan saluran produksi ke metadata strategi dan unggah bundle Cap 9 yang sesuai ke setiap saluran dengan --auto-min-update-versionUntuk upload dasar native yang sengaja tersebut, omiti --fail-on-incompatible (paket native diharapkan tidak berubah). Tahan --fail-on-incompatible dan --auto-min-update-version on everyday OTA uploads afterward. See pada setiap upload OTA sehari-hari. Lihat.
4. Keep channel and semver rules aligned so you never push a bundle that assumes Cap 9 APIs to devices still running an older native shell.

If you use Capgo Pembangunan atau CI Anda, agen pembaruan sebelum Capacitor 9 disediakan di toko sehingga pipa aliran sesuai dengan apa yang diinstal pengguna: macOS penggunaan Node 24+ dan Xcode 27+; Linux penggunaan Node 24+ dan peralatan Android host yang sesuai dengan AGP 9.2.1 / Gradle 9.5.1 (Xcode hanya tersedia untuk macOS).

Urutan operasi yang disarankan

1. Perbarui perangkat lunak yang terpasang Pada mesin CI dan mesin pengembang ke tingkat di atas (Node, Xcode, Android Studio, JDK). Tidak Meningkatkan dependensi AGP aplikasi Cap 8, wrapper Gradle, atau file proyek Android lainnya ke nilai Cap 9 sampai bunx cap migrate — langkah perubahan tersebut termasuk dalam langkah migrasi.
2. Pembaruan API native yang sudah tidak digunakan dalam aplikasi code dan plugin (terutama plugin khusus) AppDelegate Pembersihan file Gradle Android dan skrip (
3. ProGuard default, dalam skrip pengembang).gradle.propertiesPerbarui perangkat lunak yang terpasang --url skrip pengembang (di skrip pengembang).
4. Audit Cordova Penggunaan Cordova pada tingkat aplikasi; jangan mengubah plugin SPM Cordova produk hingga rilis Cap 9-saja.
5. Ketika Cap 9 sudah GA (atau ketika Anda menerima next) bun add -d @capacitor/cli@next jalankan @latest setelah rilis, lalu bunx cap migratedan ikuti setelah rilis), kemudian.
6. Publikasikan bangun native Cap 9 ke toko-toko, kemudian lanjutkan atau memperluas Capgo pembaruan OTA di saluran yang sesuai.

Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.