Come aggiornare un plugin a Capacitor a Capacitor 8

Per aggiornare un plugin Capacitor a Capacitor 8, esegui bunx @capacitor/plugin-migration-v7-to-v8@latest da radice del plugin, quindi revisiona la differenza: le dipendenze Capacitor si spostano a 8.x, gli obiettivi Android SDK 36 con minSdk 24, AGP 8.13 e Gradle 8.14.3, Kotlin va a 2.2.20 con compilerOptionse iOS passa a un target di distribuzione 15.0 con capacitor-swift-pm 8. Concludi costruendo l'app di esempio su entrambe le piattaforme e pubblicando una nuova versione maggiore.

Questa guida è per i mantenitori dei plugin. Le squadre di app dovrebbero seguire Come aggiornare la tua Capacitor App a Capacitor 8.

Cos'è cambiato per gli autori di plugin

Le strumentazioni del tuo piattaforma che hai bisogno localmente e in CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) o successivo, e un JDK 21.

Opzione 1: eseguire lo strumento di migrazione ufficiale

Dal root del plugin, su un albero Git pulito:

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

Lo strumento:

• Aggiorna le dipendenze Capacitor e imposta la versione del tuo pacchetto a 8.0.0.
• Updates dev tooling that the official template uses: @capacitor/docgen, Rollup, TypeScript @types/node, e Prettier (da v2 a v3 se utilizzi @ionic/prettier-config, più prettier-plugin-java).
• Elimina node_modules/@capacitor e package-lock.jsone poi esegue npm install. Se utilizzi Bun, quel passaggio fallisce con un avviso. Esegui bun install tu stesso in seguito e commetta bun.lock.
• Regenera il wrapper Gradle con ./gradlew wrapper --gradle-version 8.14.3.
• Riscrive build.gradle: SDK livelli, versioni AndroidX, AGP, versione Kotlin, compatibilità Java 21 e kotlinOptions per compilerOptions.
• Rialza l'obiettivo di distribuzione del podspec da 14.0 a 15.0, e in Package.swift imposta .iOS(.v15) e from: "8.0.0" per capacitor-swift-pm.

quando una stringa che si aspetta è mancante, registra Unable to find "..." in <file>. Try updating it manually. Ogni una di queste linee è un passaggio manuale per te. I plugin con logica Gradle personalizzata, cartelle non standard o file rinominati producono la maggior parte di esse.

Se Prettier è passato da v2 a v3, esegui i tuoi script di formattazione e di controllo sintassi dopo la migrazione. La differenza di formattazione può essere grande, quindi commettile separatamente dalle modifiche funzionali.

Opzione 2: aggiornamento manuale

Usa questo quando lo strumento non riesce a elaborare i tuoi file, o quando desideri esaminare ogni modifica. I passaggi seguono il Guida ufficiale all'aggiornamento del plugin.

2. Aggiornamento del plugin

{
  "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. Livelli Android SDK e sintassi 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
    }
}

Conserva il project.hasProperty(...) ? rootProject.ext... : default pattern. Consente all'app host di variables.gradle controllare i valori, il che evita la classe di errori "compilare con la versione 36" negli app.

The = Si applica solo alle proprietà. Le chiamate di metodo come mavenCentral() rimane invariato, e maven { url = "..." } ha bisogno di =.

3. Impostazioni predefinite di AndroidX

Only bump libraries your plugin actually uses. The Capacitor 8 defaults are:

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 e il wrapper 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.

4. AGP e il wrapper Gradle

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

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

Se il tuo plugin utilizza Firebase o altri servizi di Google, impostalo com.google.gms:google-services a 4.4.4.

5. Java 21 e Kotlin 2.2

Java 21 è raccomandato per AGP 8.13 e SDK 36. Java 17 funziona ancora per il plugin stesso.

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

Per i plugin Kotlin, aggiorna la versione predefinita e sposta jvmTarget fuori da kotlinOptionsKotlin 2.2 rende l'antico blocco un errore:

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

Mantieni jvmTarget e targetCompatibility su la stessa versione di Java, o Gradle si ferma con un errore di compatibilità JVM-incoerente. Se applichi ancora kotlin-android-extensionsrimuovilo. Utilizza kotlin-parcelize per @Parcelize e accesso alle viste sintetiche tramite view binding.

6. Obiettivo di distribuzione per 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")
],

Usa from:, non branch: o exact:L'applicazione generata CapApp-SPM Le impostazioni di generazione dell'app capacitor-swift-pm pin dei pacchetti @capacitor/ios l'app installata, e una gamma consente a SPM di risolvere il tuo plugin in base ad essa.

i plugin con la vecchia struttura del progetto Xcode devono anche aumentare l'obiettivo di distribuzione nel file Impostazioni di compilazione e in ios/Podfile (platform :ios, '15.0').

Se il tuo plugin non ha ancora Package.swift ancora, fai questo passo successivo. Le app create con Capacitor 8 utilizzano per impostazione predefinita SPM e passeranno al tuo plugin con un avviso "non compatibile con SPM". Segui Come migrare un plugin Capacitor a Swift Package Manager.

Opzione 3: lascia che un agente lo faccia

L'apertura Capgo Skills include capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades per salti multi-versioni, e capacitor-plugin-spm-support. Installa con bunx skills add Cap-go/capgo-skills e chiedi all'agente di aggiornare il plugin. La skill esegue lo strumento ufficiale, poi gestisce i passaggi che lo strumento segnala come saltati. Recensisci la diff nello stesso modo in cui recensiresti un PR di un tuo collega.

Cui approccio utilizzare

Inizia con lo strumento in quasi tutti i casi. Il suo log ti dice esattamente cosa resta.

Verifica prima di pubblicare

1. bun install && bun run build (o il tuo verify script).
2. Android: cd android && ./gradlew clean build test. Costruisci con JDK 21.
3. iOS con CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (nuovi plugin di layout utilizzano xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS con SPM: swift package resolve, quindi costruisci lo schema.
5. Installa il plugin in un nuovo Capacitor 8 app (bunx cap add ios viene fornito di SPM di default) e in un'app di CocoaPods. Chiamare ogni metodo pubblico su un dispositivo reale.
6. Avvia bunx cap doctor nella app di test.

Release

• Bump to a new major (the tool uses 8.0.0Aumentare a una nuova versione maggiore (lo strumento utilizza
• Scrivi un breve BREAKING.md or changelog entry: new peer range, minSdk 24, iOS 15, Java 21 for builds, any API behavior changes.
• Mantieni 7.x pubblica le correzioni per i Capacitor 7 utenti rimanenti, e pubblica quelle sotto un tag di distribuzione come latest-7.
• Aggiorna la sezione di installazione del README e la tabella di compatibilità.

Capgo mantiene un grande insieme di plugin in questo ciclo, con ogni @capgo/* aggiornamento di una Capacitor versione maggiore. Puoi esplorarli nella directory del plugin.

Troubleshooting

invalid source release: 21. Il Gradle è in esecuzione su JDK 17 o precedente. Utilizza il JDK 21 incluso in Android Studio Otter e impostalo JAVA_HOME in CI.

Unsupported class file major version 65. The opposite problem: you run JDK 21 with an old Gradle wrapper that can’t read Java 21 class files. Regenerate the wrapper at 8.14.3.

Namespace not specified. AGG 8+ richiede namespace = "..." AGP 8+ richiede android in il blocco del plugin package precedenti plugin avevano solo un AndroidManifest.xmlMozzartalo a Gradle e rimuovi package dal manifesto.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Il tuo Kotlin jvmTarget non corrisponde targetCompatibility. Imposta entrambi a 21 o entrambi a 17.

Errori che menzionano proguard-android.txt con AGP 9. Alcuni app già utilizzano AGP 9. Passa a proguard-android-optimize.txt Il tuo plugin costruisce anche in quelle app. I dettagli sono in Risolvi Capacitor errori di compilazione del plugin con AGP 9.

SPM: product 'Capacitor' required by package ... not found. La tua Package.swift riga di dipendenza contiene un errore di ortografia o utilizza una versione che non esiste. Utilizza from: "8.0.0" contro https://github.com/ionic-team/capacitor-swift-pm.git.

Avvisi di dimensione pagina di 16 KB nel Console di Play. Se il tuo plugin fornisce librerie native .so Se il tuo plugin fornisce librerie native Android 16 KB di pagina e plugin Capacitor.

Una volta che il plugin è stato aggiornato a 8, il passo successivo è prepararsi per 9. Preparing for Capacitor 9 lists the changes plugin teams can make now without breaking Capacitor 8 users.