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

Capacitor 9 tersedia di next dist-tag sambil menunggu ketersediaan umum. Anda tidak harus mengupgrade aplikasi Anda pada hari alpha mendarat, tetapi Anda harus memperhatikan petunjuk pembaruan Capacitor 9 resmi dan petunjuk pembaruan plugin perangkat lunak sudah menguraikan lantai perangkat keras dan API penghapusan yang layak ditangani awal.

Artikel ini adalah daftar persiapan Daftar Pekerjaan: pekerjaan yang dapat Anda lakukan pada Capacitor 8 (atau pada cabang) sehingga akhirnya bunx cap migrate Mengalami kesulitan bukanlah pilihan yang menarik. Ketika Anda siap untuk melakukan migrasi, ikuti panduan Ionic yang tercantum di atas baris demi baris.

Lantai alat dan platform (aplikasi)

Persiapkan CI, mesin lokal, dan pipeline penyimpanan Anda berdasarkan batasan-batasan ini:

Jika Anda masih menggunakan Capacitor 8.4 atau lebih awal untuk iOS, Anda juga memerlukan Siklus Hidup Layar Utama 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 sebagaimana dijelaskan dalam panduan resmi.

Cordova pada waktu sinkronisasi aplikasi (bukan langkah persiapan plugin)

In Capacitor 9, layer kompatibilitas Cordova telah hanya terhubung ke aplikasi Anda ketika cap sync deteksi plugin Cordova yang terinstal. Android menghapus modul Gradle tambahan ketika tidak ada yang ada; iOS menghentikan menambahkan CapacitorCordova ke Podfile atau Package.swift ketika tidak ada yang ada.

Perubahan perilaku 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.

iOS: gradle.properties dan AGP 9 default

Asisten Upgrade AGP sering menulis flag eksplisit gradle.properties sehingga bangun tetap menjalankan perilaku AGP 8. Capacitor 9 aplikasi harus menghapus entri-entri tersebut daripada membawa mereka maju: kebanyakan sudah usang sebelum AGP 10, dan beberapa mengganggu bangun Cap 9 (misalnya android.builtInKotlin=false menghilangkan dukungan Kotlin yang dibundel oleh AGP 9, dan android.sdk.defaultTargetSdkToCompileSdkIfUnset=false menghentikan AGP untuk menginfersikan targetSdkVersion).

Saat Anda melakukan migrasi, juga harapkan:

• Meningkatkan variables.gradle minimums (compile/target SDK 37, minSdkVersion 26, versi AndroidX yang diperbarui — lihat dokumen resmi).
• Menghapus flag eksplisit targetSdkVersion menggunakan aplikasi ini build.gradle sehingga AGP 9 dapat mengetahuinya dari compileSdkVersion.
• Klarifikasi variables.gradle simbol di bagian atas app/build.gradle di atas (Gradle 9.6 menghormati pencarian implicit dari proyek root).
• Ganti nama file ProGuard default, migrasi 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 di Bagian Android dan terapkan perbaikan yang sama pada cabang sebelum meningkatkan versi Capacitor.

CLI: cap run --url

Capacitor 9 menggabungkan flag live-reload host/port/https menjadi satu argumen. --url argument. Sebaliknya:

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

Passkan URL server pengembang Anda cetak:

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

Suntinglah skrip update dan potongan README sekarang agar otak otot tidak bertolak belakang dengan CLI baru setelah upgrade.

Plugin resmi: push dan splash gotcha

Perubahan dua-dua yang sering muncul di aplikasi produksi:

Pemberitahuan Push (iOS): Dikosongkan alert Opsi presentasi telah dihapus. Gunakan banner atau list Layar Splash (Android):

Layar Splash (Android): Default launchFadeOutDuration perubahan dari 200 ms ke 0Jika Anda bergantung pada efek transisi untuk menyembunyikan kegagalan pertama kali, launchFadeOutDuration: 200 dengan jelas capacitor.config Lihatlah bagian plugin di panduan pembaruan 9.0

Periksa bagian plugin di Petunjuk Pembaruan 9.0 untuk AndroidX dan perubahan versi Google Play Services yang terkait dengan plugin resmi yang Anda gunakan.

Pengembang plugin: siapkan di Cap 8 tanpa mengganggu Cap 8

Jika Anda mengirimkan plugin Capacitor yang dikonsumsi pada Capacitor 8 and Siapkan code yang siap untuk Cap 9, fokus pada penghapusan API yang sudah tidak digunakan, bukan pada perubahan pengemasan Cap-9 saja.

Aman untuk dilakukan sementara Cap 8 masih didukung:

• Ganti @NativePlugin dengan @CapacitorPlugin dan migrasikan API izin / hasil aktivitas lama ke @PermissionCallback / @ActivityCallback patterns (lihat di) Petunjuk Plugin 9.0 table).
• Ganti PluginCall.hasOption, Plugin.getConfigValuedengan CapConfig konstruktor dan getter, PluginCall.save() / isSaved()dan penghapusan Java lainnya yang terdaftar di bawah “Perubahan-perubahan yang mengganggu di code.”
• Pada iOS, hentikan penggunaan CAPBridge kelas kompatibilitas dan yang sudah tidak digunakan CAPBridgeProtocol helpers; gunakan ApplicationDelegateProxy, typed PluginCall Aksesori, dan properti bridge dari tabel migrasi.
• Run 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.

konstruktor dan getter Cordova Produk SPM dari plugin Anda Package.swift Saat ini Anda masih mendukung Capacitor 8. Cap 8 proyek mengharapkan ketergantungan itu ketika plugin Anda berbasis SPM; menghilangkannya terlalu cepat akan mengganggu konsumen yang masih menggunakan 8. Tidak opsional Cordova / menghapus kondisional Cordova produk sebagai Capacitor garis rilis 9-saja (atau semver mayor yang secara eksplisit dokumentasi sebagai Cap 9+), setelah Anda berhenti mendukung Cap 8 — seperti yang dijelaskan di panduan plugin, bukan sebagai pekerjaan persiapan pada garis Cap 8. release line (or a semver major explicitly documented as Cap 9+), after you stop supporting Cap 8 — as described in the plugin guide, not as prep work on the Cap 8 line.

Sama halnya dengan memperbarui capacitor-swift-pm to 9.0.0-alpha.x di Package.swift: yang harus dimasukkan pada Cap 9 mayor, bukan pada rilis yang kompatibel dengan Cap-8.

Capgo live update dan pembangunan toko Cap 9 native

Capgo mengirimkan bundle web update udara melalui aplikasi; shell asli masih berasal dari App Store dan Google Play. Ketika Anda memindahkan aplikasi ke Capacitor 9:

1. Angkut setidaknya satu build toko terkompiler terhadap Capacitor 9 proyek native (iOS dan Android). Binary tersebut menentukan dasar native Capgo saluran target.
2. Hanya setelah itu build telah berada di tangan pengguna, Anda dapat mengandalkan bundle OTA yang telah diuji terhadap perilaku WebView dan plugin Cap 9.
3. Tetapkan saluran produksi ke metadata strategi dan unggah bundle Cap 9 yang sesuai ke setiap saluran dengan --auto-min-update-version. Untuk upload dasar native yang sengaja tersebut, lewatkan --fail-on-incompatible (paket native diharapkan tidak berubah). Simpan --fail-on-incompatible dan --auto-min-update-version setiap pengunggahan OTA setelahnya. Lihat Alur kerja saluran Native + OTA.
4. Tetapkan aturan saluran dan semver agar Anda tidak pernah mengirimkan bundle yang mengasumsikan Cap 9 API ke perangkat yang masih menjalankan shell native yang lebih tua.

If you use Capgo Build atau agen pembaruan di CI Anda sendiri before Rilis toko Cap 9 sehingga pipa pengiriman sesuai dengan apa yang diinstal pengguna. macOS penggunaan runner memerlukan Node 24+ macOS; Linux pengguna runner memerlukan Node 24+ dan alat Android yang sesuai dengan AGP 9.2.1 / Gradle 9.5.1 (Xcode hanya tersedia untuk macOS).

Urutan operasi yang disarankan

1. Perbarui alat yang terpasang pada host CI dan mesin pengembang ke tingkat di atas (Node, Xcode, Android Studio, JDK). Tidak Naikkan 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 Pengaturan URL dan penggunaan jembatan Android.
3. Membersihkan File Gradle Android file dan skrip (gradle.properties, default ProGuard ( --url di skrip dev).
4. Mengaudit Penggunaan Cordova di tingkat aplikasi; jangan mengubah plugin SPM Cordova produk hingga rilis Cap 9-saja.
5. Ketika Cap 9 sudah GA (atau ketika Anda menerima next), jalankan bun add -d @capacitor/cli@next (atau @latest setelah rilis, kemudian bunx cap migratesetelah rilis), kemudian , dan ikuti .
6. Publikasikan Cap 9 native build ke toko-toko, kemudian lanjutkan atau memperluas Capgo OTA rollouts di saluran yang sesuai.

Capacitor 9 sebagian besar adalah “membayar kembali deprecations dan menyesuaikan dengan toolchain Android dan Apple modern.” Melakukan pekerjaan itu di Cap 8 menjaga perbedaan upgrade Anda kecil dan plugin-plugin Anda kompatibel dengan tim yang masih mengirimkan 8.x hari ini.