Bagaimana Meningkatkan Plugin Capacitor ke Capacitor 8

Untuk membuat upgrade sebuah Capacitor plugin ke Capacitor 8, jalankan bunx @capacitor/plugin-migration-v7-to-v8@latest dari akar plugin, kemudian tinjau perbedaan: dependensi Capacitor berpindah ke 8.x, target Android SDK 36 dengan minSdk 24, AGP 8.13 dan Gradle 8.14.3, Kotlin berpindah ke 2.2.20 dengan compilerOptions, dan iOS berpindah ke target pengembangan 15.0 dengan capacitor-swift-pm 8. Selesai dengan membangun aplikasi contoh pada kedua platform dan menerbitkan versi mayor baru.

Petunjuk ini untuk pengembang plugin. Tim aplikasi harus mengikuti How to Upgrade Your Capacitor App to Capacitor 8.

Apa perubahan untuk pengembang plugin

Platform tooling you need locally and in CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) or later, and a JDK 21.

Dari akar plugin, pada pohon Git yang bersih:

Dari root plugin, pada pohon git yang bersih:

bunx @capacitor/plugin-migration-v7-to-v8@latest

Alat ini:

• Mengupdate dependensi Capacitor dan mengatur versi paket Anda ke 8.0.0.
• Perangkat Lunak Pengembang yang Diperbarui yang Digunakan oleh Template Resmi: @capacitor/docgenCapacitor 8, Rollup, TypeScript, @types/nodedan Prettier (dari v2 ke v3 jika Anda menggunakan @ionic/prettier-configplus prettier-plugin-java).
• Menghapus node_modules/@capacitor dan package-lock.jsonLalu dijalankan npm install. If you use Bun, that step fails with a warning. Run bun install setelah itu dan melakukan commit bun.lock.
• sendiri setelahnya dan komit ./gradlew wrapper --gradle-version 8.14.3.
• Rewrites build.gradletingkat SDK, versi AndroidX, AGP, versi Kotlin, dan kompatibilitas Java 21 kotlinOptions to compilerOptions.
• Menambahkan target pengiriman podspec dari 14.0 menjadi 15.0, dan di Package.swift Mengatur .iOS(.v15) dan from: "8.0.0" untuk capacitor-swift-pm.

Ketika sebuah string yang diharapkan hilang, maka akan dicatat. Unable to find "..." in <file>. Try updating it manually. Setiap baris di atas adalah langkah manual untuk Anda. Plugin dengan logika Gradle yang diubah, folder yang tidak standar atau file yang diberi nama ulang menghasilkan langkah-langkah yang paling banyak.

Jika Prettier berpindah dari v2 ke v3, jalankan skrip format dan lint Anda setelah migrasi. Perbedaan format dapat sangat besar, jadi komitinya secara terpisah dari perubahan fungsional.

Option 2: Upgrade secara manual

Gunakan opsi ini ketika alat tidak dapat memparse file Anda, atau ketika Anda ingin memeriksa setiap perubahan. Langkah-langkah diikuti oleh Petunjuk Pembaruan Plugin Resmi.

1. Dependensi

{
  "devDependencies": {
    "@capacitor/android": "^8.0.0",
    "@capacitor/cli": "^8.0.0",
    "@capacitor/core": "^8.0.0",
    "@capacitor/ios": "^8.0.0"
  },
  "peerDependencies": {
    "@capacitor/core": ">=8.0.0"
  }
}

2. Android SDK tingkat dan sintaks Gradle

android {
    namespace = "com.example.plugin"
    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
    defaultConfig {
        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
    }
    lintOptions {
        abortOnError = false
    }
}

Tetapkan project.hasProperty(...) ? rootProject.ext... : default pola. Ini memungkinkan aplikasi host untuk variables.gradle mengontrol nilai-nilai, yang menghindari kelas kesalahan "compile terhadap versi 36" di aplikasi.

The = aplikasi hanya berlaku untuk properti. Panggilan metode seperti mavenCentral() Lainnya dari daftar resmi: maven { url = "..." } memerlukan =.

3. Default AndroidX

Hanya tingkatkan library yang benar-benar digunakan oleh plugin Anda. Default Capacitor 8 adalah:

ext {
    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
    androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}

4. AGP dan pengguna Gradle androidxCoordinatorLayoutVersion 1.3.0, androidxFragmentVersion 1.8.9, firebaseMessagingVersion 25.0.1, androidxBrowserVersion 1.9.0, androidxMaterialVersion 1.13.0, androidxExifInterfaceVersion 1.4.1, coreSplashScreenVersion 1.2.0.

5. AGP dan pengguna Gradle

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
    }
}

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

Jika plugin Anda menggunakan Firebase atau layanan Google lainnya, atur com.google.gms:google-services ke 4.4.4.

5. Java 21 dan Kotlin 2.2

Java 21 direkomendasikan untuk AGP 8.13 dan SDK 36. Java 17 masih berfungsi untuk plugin itu sendiri.

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

Untuk plugin Kotlin, update versi default dan pindahkan jvmTarget keluar dari kotlinOptions. Kotlin 2.2 membuat blok lama menjadi kesalahan:

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

buildscript {
    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
}

android {
    // remove: kotlinOptions { jvmTarget = '17' }
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_21
    }
}

Tetapkan jvmTarget dan targetCompatibility Jika Anda masih menggunakan versi Java yang sama, atau Gradle berhenti dengan pesan kesalahan "Inkonsistensi kompatibilitas JVM-target", kotlin-android-extensionsUpgrade Plugin Capacitor ke Capacitor 8 kotlin-parcelize for @Parcelize dan pengikat tampilan untuk akses sintetis view.

6. Target pengembangan iOS

Podspec:

s.ios.deployment_target = '15.0'

Package.swift:

platforms: [.iOS(.v15)],
dependencies: [
    .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
],

Pilih from:, bukan branch: atau exact:Aplikasi yang dihasilkan CapApp-SPM . Aplikasi yang dihasilkan capacitor-swift-pm hingga versi yang tepat dari @capacitor/ios ke versi tepat aplikasi yang diinstal, dan rentang memungkinkan SPM menyelesaikan plugin terhadapnya.

Plugin dengan tata letak proyek Xcode lama juga memerlukan target pengembangan yang dinaikkan di pengaturan proyek Pengaturan Pembangunan dan di ios/Podfile (platform :ios, '15.0').

Jika plugin Anda belum Package.swift lakukan hal itu selanjutnya. Aplikasi yang dibuat dengan Capacitor 8 secara default menggunakan SPM dan akan melewatkan plugin Anda dengan peringatan “tidak kompatibel dengan SPM”. Ikuti Bagaimana Migrasi Plugin Capacitor ke Manager Paket Swift.

Pilihan 3: biarkan agen melakukan hal itu

Terbuka Keterampilan Capgo termasuk capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades untuk melompat versi, dan capacitor-plugin-spm-support. Pasang dengan bunx skills add Cap-go/capgo-skills dan minta agen Anda untuk mengupgrade plugin. Kemampuan ini menjalankan alat resmi, kemudian mengelola langkah-langkah yang tertinggal. Tinjau perbedaan yang sama seperti Anda tinjau PR teman Anda.

Metode mana yang harus digunakan

Mulai dengan alat dalam hampir semua kasus. Lognya menginformasikan apa yang masih belum selesai.

Pastikan sebelum Anda mempublikasikan.

1. bun install && bun run build (or your verify Android:
2. Android: cd android && ./gradlew clean build testiOS dengan CocoaPods:
3. (plugin layout baru menggunakan) cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (new layout plugin menggunakan) xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. , kemudian bangun skema. swift package resolveLalu bangunlah skema.
5. Instal plugin di aplikasi Capacitor 8 yang segar (bunx cap add ios Memberi Anda SPM secara default) dan di aplikasi CocoaPods. Pemanggilan setiap metode publik pada perangkat nyata.
6. Jalankan bunx cap doctor di aplikasi uji coba.

Rilis

• Naikkan ke versi baru utama (alat ini menggunakan 8.0.0) Meningkatkan minSdk dan lantai iOS adalah perubahan yang memecahkan untuk konsumen.
• Tulislah ringkasan singkat BREAKING.md atau catatan perubahan: rentang peer baru, minSdk 24, iOS 15, Java 21 untuk pembangunan, setiap perubahan perilaku API.
• Tetapkan 7.x cabang jika Anda masih mengirimkan perbaikan untuk pengguna Capacitor 7, dan publikasikan mereka di bawah tag distribusi seperti latest-7.
• Perbarui bagian instalasi README dan tabel kompatibilitas.

Capgo menjaga set besar plugin pada siklus ini, dengan setiap @capgo/* versi utama mengikuti Capacitor utama. Anda dapat melihatnya di directory plugin.

Troubleshooting

invalid source release: 21. Gradle berjalan di JDK 17 atau lebih lama. Gunakan JDK 21 yang dibundel dengan Android Studio Otter dan tetapkan JAVA_HOME di CI.

Unsupported class file major version 65. Masalah sebaliknya: Anda menjalankan JDK 21 dengan wrapper Gradle yang sudah ketinggalan zaman dan tidak dapat membaca file kelas Java 21. Regenerasi wrapper di 8.14.3.

Namespace not specified. AGP 8+ memerlukan namespace = "..." dalam blok plugin. android atribut lama hanya ada di package . Pindahkan ke Gradle dan hapus AndroidManifest.xmlPindahkan ke Gradle dan hapus package dari manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). di jvmTarget tidak sesuai targetCompatibilityAtur kedua-duanya ke 21 atau kedua-duanya ke 17.

Kesalahan yang menyebutkan proguard-android.txt dengan AGP 9. Beberapa aplikasi sudah menjalankan AGP 9. Pindah ke proguard-android-optimize.txt so your plugin builds in those apps too. Details are in perbaiki kesalahan pembangunan plugin Capacitor dengan AGP 9.

SPM: product 'Capacitor' required by package ... not found. Your Package.swift baris dependensi memiliki kesalahan penulisan atau menggunakan versi yang tidak ada. Gunakan from: "8.0.0" against https://github.com/ionic-team/capacitor-swift-pm.git.

Peringatan ukuran halaman 16 KB di Console Play. Jika plugin Anda menyebarkan perangkat lunak asli .so perangkat lunak asli dengan pengaturan 16 KB. Android 16 KB halaman ukuran dan plugin Capacitor.

Android 16 KB halaman ukuran dan __CAPGO_KEEP_0__ plugin Preparing for Capacitor 9 lists the changes plugin teams can make now without breaking Capacitor 8 users.