How to Upgrade Your Capacitor App to Capacitor 8

Untuk mengupgrade sebuah aplikasi Capacitor ke Capacitor 8, instal Node.js 22+, Xcode 26+ dan Android Studio Otter, update @capacitor/cli ke versi terbaru 8.x, jalankan bunx cap migrate, kemudian perbaiki apa pun yang dilaporkan oleh migrator. Perubahan utama yang mengganggu adalah iOS 15 sebagai target pengembangan minimum, Android SDK 36 dengan minSdk 24, AGP 8.13 dengan Gradle 8.14.3, dan penghapusan adjustMarginsForEdgeToEdge di sisi baru plugin Bar Sistem.

Petunjuk ini menjelajahi jalur otomatis, setiap langkah manual di belakangnya, dan kesalahan yang paling sering dialami orang setelah upgrade. Jika Anda menjaga plugin daripada aplikasi, baca How to Upgrade Your Capacitor Plugin to Capacitor 8 sebaliknya.

Persyaratan Capacitor 8 secara singkat

Periksa toolchain Anda sebelum menyentuh proyek. Banyak upgrade gagal karena JDK yang lama, Xcode yang lama, atau Node yang lama di CI, bukan code.

Xcode 26 bukan hanya Capacitor yang diperlukan. Sejak 28 April 2026, App Store Connect menolak unggahan yang dibangun dengan Xcode yang lebih tua, jadi Anda memerlukannya secara otomatis. Lihat Persyaratan Xcode 26 untuk Capacitor untuk informasi lebih lanjut.

Sebelum Anda memulai

1. Commit semua perubahan, atau buat cabang. Migrator mengedit file asli di tempat.
2. Pastikan aplikasi Anda dapat dibangun pada Capacitor 7 hari ini. Mengupgrade proyek yang rusak hanya akan menambah kebisingan.
3. Jika Anda menggunakan Capacitor 6 atau lebih lama, lakukan pembaruan besar sebelumnya terlebih dahulu. Setiap pembaruan besar memiliki logika migrasinya sendiri di CLI.
4. Daftar plugin Anda dengan bunx cap ls periksa bahwa setiap satu memiliki rilis yang mendukung Capacitor 8. Lihatlah peerDependencies dan pastikan setiap plugin memiliki rilis yang mendukung __CAPGO_KEEP_0__ 8. Lihat pada

bun pm view @capgo/capacitor-updater peerDependencies

A plugin dengan @capacitor/core: ^7.0.0 sebagai teman akan menginstal dengan peringatan dan mungkin gagal untuk dikompilasi. Capgo plugin mengikuti Capacitor major dalam versi mereka sendiri, jadi @capgo/* 8.x rilis mengarahkan ke Capacitor 8.

5. Perbarui toolkit lokal dan CI: Node 22, Xcode 26, JDK 21, Android Studio Otter. Di GitHub Actions, pinkan gambar macOS yang mengirim Xcode 26 dan gunakan actions/setup-java dengan java-version: '21'.

Option 1: perbarui dengan cap migrate

Pengiriman CLI menyediakan perintah migrasi yang mengelola sebagian besar pekerjaan. Install versi terbaru CLI, kemudian jalankan:

bun add -D @capacitor/cli@latest
bunx cap migrate

The migrator bertanya apakah harus menginstal paket Capacitor baru dan memungkinkan Anda memilih npm, Yarn, pnpm atau Bun. Pilih Bun jika proyek Anda memiliki bun.lock. Anda dapat melewatkan prompt dengan bunx cap migrate --noprompt.

Apa yang berubah untuk Anda:

• Bumps @capacitor/core, @capacitor/ios, @capacitor/android dan resmi @capacitor/* mengupgrade plugin ke 8.x.
• Set IPHONEOS_DEPLOYMENT_TARGET = 15.0 dalam proyek Xcode dan platform :ios, '15.0' dalam Podfile.
• Pembaruan variables.gradleMengupgrade Aplikasi Capacitor ke Capacitor 8 kotlin_version.
• Pembaruan density context android:configChanges in AndroidManifest.xml.

Read the full output. When a step cannot be applied, for example because a file was customized, the CLI prints an error with the file name and continues. Those lines are your manual to-do list.

Saat selesai:

bun run build
bunx cap sync

Buka setiap platform dan bangunlah satu kali dari IDE sehingga Anda melihat kesalahan native secara lengkap.

Option 2: mengupgrade secara manual

Jika proyek asli Anda telah disesuaikan secara berat, atau migrator melewatkan langkah-langkah, terapkan perubahan secara manual. Perubahan-perubahan ini sesuai dengan petunjuk upgrade resmi Capacitor ke versi 8.

Perbarui paket-paket npm

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

Kemudian perbarui setiap plugin resmi, misalnya:

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

iOS: naikkan target pengembangan ke 15.0

Dalam Xcode, pilih proyek, buka Pengaturan Pembangunan, cari Target Pengembangan iOS di bawah Pengaturan dan atur menjadi 15.0. Ulangi untuk setiap target aplikasi, termasuk ekstensi.

Jika aplikasi masih menggunakan CocoaPods, update ios/App/Podfile:

platform :ios, '15.0'

Lalu jalankan bunx cap sync ios, yang menjalankan pod install untuk Anda.

Jika aplikasi menggunakan SPM, file CLI regenerasi ios/App/CapApp-SPM/Package.swift setiap sinkron dengan versi platform yang tepat dan versi yang tepat capacitor-swift-pm yang sesuai dengan aplikasi yang terpasang @capacitor/ios. Jangan edit file tersebut secara manual.

iOS: hapus notifikasi pengontrol tampilan kustom

Capacitor 8 sekarang mengeluarkan CAPBridgeViewController notifikasi untuk viewDidAppear dan viewWillTransition itu sendiri. Jika Anda menambahkan ekstensi atau subclass ke post .capacitorViewDidAppear atau .capacitorViewWillTransitionatau, hapusnya, atau pendengar akan mengalami guncangan ganda.

Android: update Studio Android dan AGP

Buka Android Studio Otter atau yang lebih baru, buka android Tools > Asisten Perbarui AGP Tools > Asisten Pengupgrade AGPPilih 8.13.0 dan jalankan langkah-langkah yang dipilih. Atau edit android/build.gradle Android: update

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

atau android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

Android: update variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

Tetapkan variabel tambahan yang digunakan oleh plugin (misalnya firebaseMessagingVersionTermasuk dalam pembaruan resmi plugin Capacitor 8 adalah firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' dan androidxExifInterfaceVersion = '1.4.1'.

Android: ubah ke = penugasan dalam file Gradle

Sintaks spasial Gradle telah dihapus. Saat ini, Gradle hanya memberi peringatan, tetapi akan mengganggu dalam rilis Gradle di masa depan, jadi perbaiki sekarang di} android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

Panggilan metode seperti google() atau mavenCentral() tetaplah seperti itu.

Android: Kotlin dan configChanges

Jika modul aplikasi Anda menggunakan Kotlin, atur kotlin_version = '2.2.20'Kotlin 2.x mengubah versi lama kotlinOptions {} mengubah blok menjadi kesalahan, jadi pindahkan jvmTarget ke kotlin { compilerOptions { ... } }.

Tambahkan density ke aktivitas utama sehingga WebView tidak dibuat ulang ketika densitas layar berubah (perangkat lipat, pengaturan ukuran jendela, pengaturan ukuran layar):

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android: layout bridge telah diubah nama

bridge_layout_main.xml tidak ada lagi. Jika Anda menggunakan MainActivity atau fragment fragment yang dimodifikasi R.layout.bridge_layout_main, gunakan R.layout.capacitor_bridge_layout_main.

Edge-to-edge dan plugin baru System Bars

Ini adalah perubahan yang paling mungkin menampilkan secara visual. Capacitor 8 telah dihapus android.adjustMarginsForEdgeToEdge dan menambahkan plugin System Bars inti. Anda tidak menginstalnya, karena itu sudah ada di @capacitor/core.

Android 15 memaksa edge-to-edge untuk aplikasi yang mengtarget SDK 35, dan Android 16 menghapus opsi keluar untuk aplikasi yang mengtarget SDK 36. Capacitor 8 mengtarget 36, sehingga konten web Anda sekarang menampilkan di belakang bilah status dan navigasi kecuali Anda menghandle insets.

Plugin konfigurasi hidup di bawah plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

Dengan css atau nativeAndroid WebViews yang lebih baru (Chromium 140+) viewport-fit=cover dan melaporkan real env(safe-area-inset-*) Nilai-nilai. Pada WebView yang lebih tua, Capacitor memanjangkan WebView dan menetapkan nilai env ke 0pxJadi, atur tag meta dan gunakan variabel:

<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);
}

Jadi tetapkan tag meta dan gunakan variabel-variabel:

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Ionic Framework aplikasi sudah menggunakan variabel safe-area, jadi biasanya mereka hanya memerlukan tag meta. Aplikasi Ionic Framework sudah menggunakan variabel zona aman, sehingga biasanya mereka hanya membutuhkan tag meta. Artikel kami yang lebih tua tentang Menggambarkan pilihan Capacitor 7, yang tidak ada lagi di 8.

Perubahan perilaku lain yang perlu diperiksa

• appendUserAgent On iOS: Capacitor 7 menambahkan dua spasi sebelum string Anda, Capacitor 8 menambahkan satu. Jika server Anda memproses agent pengguna secara ketat, tambahkan spasi di awal ios.appendUserAgent (bukan opsi root, yang juga mempengaruhi Android)
• Pengaturan Layar dan Scanner Barcode: pada Android 16+ layar besar, pengunci orientasi diabaikan. Opt-out sementara ada melalui properti manifest, tetapi Android 17 menghilangkannya android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY Properti manifest, tetapi Android 17 menghilangkannya.
• Geolocation: timeout Sekarang berlaku untuk semua permintaan pada Android dan iOS. Jika Anda melihat waktu tunggu baru, tingkatkan nilai tersebut. watchPosition mendapatkan di Android interval Pengatur Status
• Status BarPengaturan Layar dan Scanner Barcode CAPBridgeViewController berkas notifikasi, karena inti sekarang mengeluarkan event-event tersebut.
• Platform iOS baru secara default menggunakan SPM: bunx cap add ios sekarang membuat proyek SPM. Gunakan --packagemanager CocoaPods jika Anda membutuhkan template lama. Lihat bagaimana menggunakan CocoaPods dengan Capacitor 8.

Verifikasi pembaruan

Jalankan daftar ini pada kedua platform sebelum Anda rilis:

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor menampilkan versi 8.x yang sesuai untuk inti, CLI, iOS dan Android.
• Aplikasi meluncur, layar splash menyembunyikan, tautan dalam membuka layar yang benar.
• Area status bar dan navigation bar terlihat benar pada perangkat Android 15/16 dan pada iPhone yang memiliki notch.
• Pemberitahuan push, kamera, akses file dan plugin mana pun dengan izin native masih berfungsi.
• Rilis build (Arsip di Xcode, ./gradlew bundleReleaseberhasil, bukan hanya debug.

Jika Anda tidak ingin menjaga Xcode 26 dan JDK 21 di setiap mesin, Capgo Build menggunakan Cloud untuk menjalankan build iOS dan Android dengan alat-alat yang saat ini digunakan.

Ship the upgrade safely with live updates

A Capacitor major upgrade changes native code, so it has to go through the App Store and Google Play. Web bundles built after the upgrade may call plugin APIs that older binaries don’t have.

If you use Sebuah Capgo peningkatan besar mengubah native __CAPGO_KEEP_1__, sehingga harus melalui App Store dan Google Play. Paket web yang dibuat setelah peningkatan mungkin memanggil API plugin yang tidak dimiliki oleh biner yang lebih tua., keep Capacitor 7 users and Capacitor 8 users apart until adoption catches up: bump your native version, upload new bundles to a channel used by the new binary, and run the __CAPGO_KEEP_0__ pembaruan hidup sebelum Anda mengunggah:

bunx @capgo/cli@latest bundle compatibility

Perbandingan versi plugin native di dalam bundle Anda dengan apa yang berjalan di saluran dan menandai kesalahan sebelum pengguna mendapatkan pembaruan yang rusak.

Memecahkan masalah Capacitor 8 upgrade umum

The engine "node" is incompatible atau CLI menolak berjalan. Anda menggunakan Node 20 atau lebih lama. Pasang Node 22 LTS, dan update gambar CI Anda juga.

error: invalid source release: 21 di Android. Gradle menjalankan JDK 17. Pilih Android Studio ke JDK bundel 21 (Settings > Bangun, Eksekusi, dan Pengiriman > Bangun Alat > Gradle > JDK Gradle) dan atur JAVA_HOME ke JDK 21 untuk build perintah baris dan CI.

Minimum supported Gradle version is 8.13. Anda telah memperbarui AGP tetapi tidak wrapper. Atur wrapper ke 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion masih 35 di mana saja. Periksa variables.gradle and any plugin that hardcodes it.

Using 'kotlinOptions' ... is an error atau kesalahan DSL Kotlin yang mirip. Plugin atau modul aplikasi Anda masih menggunakan kotlinOptionsPerbarui plugin, atau patch hingga rilis tiba (lihat bagaimana cara mempatch plugin Capacitor).

Xcode: No such module 'Capacitor' setelah diperbarui. For CocoaPods, buka App.xcworkspace, bukan App.xcodeprojdan jalankan ulang bunx cap sync ios. Untuk SPM, gunakan File > Packages > Reset Package Caches.

"X" plugin is not implemented on ios/android. Plugin tidak terintegrasi, atau tidak memiliki Capacitor 8 / SPM-compatible rilis. Jalankan bunx cap sync dan baca peringatan.

Untuk daftar panjang, lihat Capacitor Panduan troubleshooting iOS dan dan panduan troubleshooting Android. Versi inti dan plugin yang tidak sesuai dibahas dalam fix Capacitor kesalahan versi yang tidak sesuai.

Biarkan agen AI melakukan bagian yang membosankan

Jika Anda menggunakan Claude Code, Cursor atau agen serupa, buka Capgo Kemampuan termasuk capacitor-app-upgrade-v7-to-v8 dan capacitor-app-upgrades untuk melompat ke mayor. Instal mereka dengan bunx skills add Cap-go/capgo-skills and ask the agent to upgrade the app. It runs the migrator, then checks the steps the CLI usually misses, such as Gradle syntax, Kotlin options and CI images.

Apa yang akan datang

Capacitor 9 sudah dalam tahap pra-rilis. Setelah Anda stabil di 8, baca Mengpersiapkan Capacitor 9 sehingga upgrade berikutnya lebih kecil.