So aktualisierst du ein Capacitor Plugin auf Capacitor 8

Um ein Capacitor Plugin auf Capacitor 8 zu upgraden, führe aus: bunx @capacitor/plugin-migration-v7-to-v8@latest im Plugin-Root, und prüfe dann den Diff: Capacitor Dependencies wechseln auf 8.x, Android zielt auf SDK 36 mit minSdk 24, AGP 8.13 und Gradle 8.14.3, Kotlin geht auf 2.2.20 mit compilerOptions, und iOS wechselt zu einem Deployment-Target von 15.0 mit capacitor-swift-pm 8. Beende den Prozess, indem du die Beispiel-App auf beiden Plattformen baust und eine neue Major-Version veröffentlichst.

Dieser Guide richtet sich an Plugin-Maintainer. App-Teams sollten So aktualisierst du deine Capacitor App auf Capacitor 8.

Was sich für Plugin-Autoren ändert

Lokale und CI-Tooling-Anforderungen: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) oder neuer sowie JDK 21.

Option 1: Das offizielle Migration-Tool nutzen

Im Plugin-Root, in einem sauberen Git-Tree:

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

Das Tool:

• Aktualisiert die Capacitor Dependencies und setzt deine Package-Version auf 8.0.0.
• Aktualisiert die Dev-Tools, die das offizielle Template nutzt: @capacitor/docgen, Rollup, TypeScript, @types/node, und Prettier (von v2 auf v3, falls du @ionic/prettier-config, plus prettier-plugin-java).
• Löscht node_modules/@capacitor und package-lock.json, führt dann aus npm install. Wenn du Bun nutzt, schlägt dieser Schritt mit einer Warnung fehl. Führe bun install danach selbst aus und committe bun.lock.
• Regeneriert den Gradle Wrapper mit ./gradlew wrapper --gradle-version 8.14.3.
• Schreibt neu build.gradle: SDK Levels, AndroidX-Versionen, AGP, Kotlin-Version, Java 21-Kompatibilität und kotlinOptions zu compilerOptions.
• Erhöht das Podspec-Deployment-Target von 14.0 auf 15.0 und in Package.swift setzt .iOS(.v15) und from: "8.0.0" für capacitor-swift-pm.

Wenn eine erwartete String fehlt, wird protokolliert Unable to find "..." in <file>. Try updating it manually. Jede dieser Zeilen ist ein manueller Schritt für dich. Plugins mit eigener Gradle-Logik, nicht standardmäßigen Ordnern oder umbenannten Dateien erzeugen am meisten davon.

Wenn Prettier von v2 auf v3 migriert wurde, führe nach der Migration deine Format- und Lint-Skripte aus. Die Formatierungs-Diffs können umfangreich sein, daher solltest du sie getrennt von den funktionalen Änderungen committen.

Option 2: Manuell upgraden

Nutze dies, wenn das Tool deine Dateien nicht parsen kann oder wenn du jede Änderung überprüfen möchtest. Die Schritte folgen dem offiziellen Plugin-Upgrade-Guide.

1. Abhängigkeiten

{
  "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-Level und Gradle-Syntax

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

Behalte das project.hasProperty(...) ? rootProject.ext... : default Muster. Es ermöglicht der Host-App, variables.gradle die Werte zu steuern, was Fehler der Art „compile against version 36“ in Apps vermeidet.

Der = Syntax gilt nur für Eigenschaften. Method Calls wie mavenCentral() bleiben unverändert, und maven { url = "..." } benötigt die =.

3. AndroidX-Defaults

Aktualisiere nur die Bibliotheken, die dein Plugin tatsächlich verwendet. Die Capacitor 8-Defaults sind:

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

Weitere aus der offiziellen Liste: 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 und der Gradle-Wrapper

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

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

Falls dein Plugin Firebase oder andere Google Services nutzt, setze com.google.gms:google-services zu 4.4.4.

5. Java 21 und Kotlin 2.2

Java 21 wird für AGP 8.13 und SDK 36 empfohlen. Java 17 funktioniert weiterhin für das Plugin selbst.

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

Bei Kotlin-Plugins aktualisiere die Standardversion und verschiebe jvmTarget aus kotlinOptions. Kotlin 2.2 macht den alten Block zum Fehler:

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

Behalten jvmTarget und targetCompatibility auf derselben Java-Version, sonst bricht Gradle mit einem „Inconsistent JVM-target compatibility“-Fehler ab. Falls du noch kotlin-android-extensionsverwendest, entferne es. Nutze kotlin-parcelize für @Parcelize und View-Binding für synthetischen View-Zugriff.

6. iOS-Deployment-Ziel

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")
],

Nutzt from:, nicht branch: oder exact:. Die generierte App CapApp-SPM Pinned Pakete capacitor-swift-pm auf die exakte Version von @capacitor/ios der installierten App, und ein Bereich lässt SPM dein Plugin dagegen auflösen.

Plugins mit dem alten Xcode-Projektlayout müssen auch das Deployment-Target im Projekt erhöhen in Build-Einstellungen und in ios/Podfile (platform :ios, '15.0').

Wenn dein Plugin noch kein Package.swift hat, mach das als Nächstes. Apps, die mit Capacitor 8 erstellt wurden, verwenden standardmäßig SPM und überspringen dein Plugin mit einer „nicht SPM-kompatibel“-Warnung. Folge So migrierst du ein Capacitor-Plugin auf Swift Package Manager.

Option 3: Lass einen Agenten erledigen

Das offene Capgo Skills einschließen capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades für Sprünge über mehrere Versionen, und capacitor-plugin-spm-support. Installieren mit bunx skills add Cap-go/capgo-skills und bitte deinen Agenten, das Plugin zu upgraden. Der Skill führt das offizielle Tool aus und übernimmt dann die Schritte, die das Tool als übersprungen markiert. Überprüfe den Diff so, wie du auch den PR eines Teamkollegen prüfen würdest.

Welchen Ansatz wählen?

Beginne in fast jedem Fall mit dem Tool. Das Log zeigt dir genau, was noch fehlt.

Verifizieren vor der Veröffentlichung

1. bun install && bun run build (oder dein verify Skript).
2. Android: cd android && ./gradlew clean build test. Build mit JDK 21.
3. iOS mit CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (neue Layout-Plugins nutzen xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS mit SPM: swift package resolve, dann das Scheme bauen.
5. Installiere das Plugin in eine frische Capacitor 8-App (bunx cap add ios standardmäßig SPM) und in eine CocoaPods-App. Rufe jede öffentliche Methode auf einem echten Gerät auf.
6. Ausführen bunx cap doctor in der Test-App.

Release

• Erhöhe auf eine neue Major-Version (das Tool nutzt 8.0.0). Das Erhöhen von minSdk und der iOS-Mindestversion ist ein Breaking Change für Nutzer.
• Schreibe eine kurze BREAKING.md oder Changelog-Eintrag: neue peer range, minSdk 24, iOS 15, Java 21 für Builds, Verhaltensänderungen in API.
• Behalte eine 7.x Branch bei, falls du noch Fixes für Capacitor 7-Nutzer veröffentlichst, und veröffentliche diese unter einem dist-tag wie latest-7.
• Aktualisiere den Installationsabschnitt im README und die Kompatibilitätstabelle.

Capgo pflegt eine große Auswahl an Plugins in diesem Zyklus, wobei jede @capgo/* Major-Version einer Capacitor Major-Version entspricht. Du kannst sie im Plugin-Verzeichnis.

Fehlerbehebung

invalid source release: 21. Gradle läuft auf JDK 17 oder älter. Verwende das mit Android Studio Otter ausgelieferte JDK 21 und setze JAVA_HOME in der CI.

Unsupported class file major version 65. Das umgekehrte Problem: Du nutzt JDK 21 mit einem alten Gradle Wrapper, der Java-21-Klassendateien nicht lesen kann. Erzeuge den Wrapper mit 8.14.3 neu.

Namespace not specified. AGP 8+ erfordert namespace = "..." in the plugin’s android Block. Ältere Plugins hatten nur ein package Attribut in AndroidManifest.xml. Verschiebe es nach Gradle und entferne package aus dem Manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Dein Kotlin- jvmTarget stimmt nicht mit targetCompatibilityüberein. Setze beide auf 21 oder beide auf 17.

Fehlermeldungen mit proguard-android.txt bei AGP 9. Einige Apps nutzen bereits AGP 9. Wechsle zu proguard-android-optimize.txt , damit dein Plugin auch in diesen Apps gebaut wird. Details findest du in Capacitor Plugin-Buildfehler mit AGP 9 beheben.

SPM: product 'Capacitor' required by package ... not found. Dein Package.swift Die Abhängigkeitszeile enthält einen Tippfehler oder verwendet eine nicht vorhandene Version. Verwende from: "8.0.0" gegenüber https://github.com/ionic-team/capacitor-swift-pm.git.

16-KB-Seitengrößen-Warnungen in der Play Console. Wenn dein Plugin native .so Bibliotheken enthält, baue sie mit 16-KB-Ausrichtung neu. Siehe Android 16 KB Seitengröße und Capacitor Plugins.

Sobald das Plugin auf 8 ist, ist der nächste Schritt die Vorbereitung auf 9. Vorbereitung auf Capacitor 9 listet die Änderungen auf, die Plugin-Teams jetzt vornehmen können, ohne Capacitor 8-Nutzer zu beeinträchtigen.