So aktualisierst du deine Capacitor App auf Capacitor 8

Um eine Capacitor App auf Capacitor 8 zu upgraden, installiere Node.js 22+, Xcode 26+ und Android Studio Otter, aktualisiere @capacitor/cli auf die neueste 8.x-Version und führe aus bunx cap migrate, und behebe dann die vom Migrationsassistenten gemeldeten Probleme. Die wichtigsten Breaking Changes sind iOS 15 als Mindest-Deployment-Target, Android SDK 36 mit minSdk 24, AGP 8.13 mit Gradle 8.14.3 sowie die Entfernung von adjustMarginsForEdgeToEdge zugunsten des neuen System Bars-Plugins.

Dieser Guide führt durch den automatisierten Pfad, alle manuellen Schritte dahinter und die häufigsten Fehler nach dem Upgrade. Wenn du ein Plugin statt einer App pflegst, lies So upgrade dein Capacitor-Plugin auf Capacitor 8 stattdessen.

Capacitor 8-Anforderungen auf einen Blick

Prüfe deine Toolchain, bevor du das Projekt anfasst. Die meisten fehlgeschlagenen Upgrades sind auf ein altes JDK, ein altes Xcode oder ein altes Node in der CI zurückzuführen, nicht auf das code.

Xcode 26 ist nicht nur eine Anforderung von Capacitor. Seit dem 28. April 2026 lehnt App Store Connect Uploads ab, die mit einem älteren Xcode gebaut wurden, du brauchst es also sowieso. Siehe Apples Xcode-26-Anforderung für Capacitor Apps für die Details.

Bevor du startest

1. Committe alles oder erstelle einen Branch. Der Migrator bearbeitet die nativen Dateien direkt.
2. Stelle sicher, dass die App heute mit Capacitor 7 buildet. Ein kaputtes Projekt zu upgraden, erzeugt nur unnötigen Aufwand.
3. Falls du auf Capacitor 6 oder älter bist, mach zuerst das vorherige Major-Upgrade. Jedes Major hat seine eigene Migrationslogik im CLI.
4. Liste deine Plugins mit bunx cap ls auf und prüfe, ob jedes Plugin eine Version hat, die Capacitor 8 unterstützt. Schau dir die peerDependencies der neuesten Version:

bun pm view @capgo/capacitor-updater peerDependencies

Ein Plugin mit @capacitor/core: ^7.0.0 als Peer wird mit Warnungen installiert und kann beim Kompilieren fehlschlagen. Capgo Plugins folgen in ihrer eigenen Versionsnummer der Capacitor-Major-Version, daher @capgo/* zielen 8.x Releases auf Capacitor 8 ab.

5. Lokale und CI-Toolchains aktualisieren: Node 22, Xcode 26, JDK 21, Android Studio Otter. Pinne in GitHub Actions ein macOS-Image, das Xcode 26 enthält, und nutze actions/setup-java mit java-version: '21'.

Option 1: Upgrade mit cap migrate

Das CLI bringt einen Migration-Command mit, der den Großteil der Arbeit erledigt. Installiere das neueste CLI und führe ihn dann aus:

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

Der Migrator fragt, ob die neuen Capacitor Pakete installiert werden sollen, und lässt dich npm, Yarn, pnpm oder Bun auswählen. Wähle Bun, falls dein Projekt ein bun.lock. Den Prompt kannst du überspringen mit bunx cap migrate --noprompt.

Was sich für dich ändert:

• Bumps @capacitor/core, @capacitor/ios, @capacitor/android und offizielle @capacitor/* Plugins auf 8.x.
• Legt fest IPHONEOS_DEPLOYMENT_TARGET = 15.0 im Xcode-Projekt und platform :ios, '15.0' in der Podfile.
• Updates variables.gradle, die AGP-Classpath, den Gradle-Wrapper und kotlin_version.
• Fügt hinzu density zu android:configChanges in einem AndroidManifest.xml.

Lies die vollständige Ausgabe. Wenn ein Schritt nicht angewendet werden kann, z. B. weil eine Datei angepasst wurde, gibt CLI einen Fehler mit dem Dateinamen aus und fährt fort. Diese Zeilen sind deine manuelle To-do-Liste.

Wenn es fertig ist:

bun run build
bunx cap sync

Öffne dann jede Plattform und baue sie einmal in der IDE, damit du native Fehler vollständig siehst.

Option 2: Manuell upgraden

Falls deine nativen Projekte stark angepasst wurden oder der Migrator Schritte übersprungen hat, wende die Änderungen manuell an. Diese entsprechen dem offiziellen Capacitor 8 Upgrade-Guide.

Aktualisiere die npm Packages

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

Aktualisiere anschließend jedes offizielle Plugin, zum Beispiel:

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

iOS: Erhöhe das Deployment Target auf 15.0

Wähle in Xcode das Projekt aus und öffne Build-Einstellungen, suche nach iOS-Deployment-Ziel unter Deployment und setze es auf 15.0. Wiederhole das für jedes App-Target, einschließlich Extensions.

Wenn die App noch CocoaPods nutzt, aktualisiere ios/App/Podfile:

platform :ios, '15.0'

Führe dann bunx cap sync ios, das ausgeführt wird pod install für dich.

Wenn die App SPM nutzt, regeneriert CLI ios/App/CapApp-SPM/Package.swift bei jedem Sync mit der passenden Plattformversion und einer exakten capacitor-swift-pm Version, die zu deiner installierten passt @capacitor/ios. Bearbeite diese Datei nicht manuell.

iOS: Custom View Controller Notifications entfernen

Capacitor 8 sendet jetzt CAPBridgeViewController Benachrichtigungen für viewDidAppear und viewWillTransition selbst. Falls du eine Erweiterung oder eine Unterklasse hinzugefügt hast, um .capacitorViewDidAppear oder .capacitorViewWillTransition, entferne sie, sonst werden die Listener doppelt ausgelöst.

Android: Android Studio und AGP aktualisieren

Installiere Android Studio Otter oder neuer und öffne die android Ordner und führe aus Tools > AGP Upgrade Assistant. Wähle 8.13.0 und führe die ausgewählten Schritte aus. Oder bearbeite android/build.gradle direkt:

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

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

Behalte alle zusätzlichen Variablen, die deine Plugins lesen (z. B. firebaseMessagingVersion). Offizielle Plugin-Updates für Capacitor 8 beinhalten firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' und androidxExifInterfaceVersion = '1.4.1'.

Android: umstellen auf = Zuweisung in Gradle-Dateien

Gradle hat die Space-Assignment-Syntax als deprecated markiert. Heute gibt es nur eine Warnung, aber in einem zukünftigen Gradle-Release wird sie brechen. Fixe das jetzt in 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:!*~'
         }
     }
}

Methodenaufrufe wie google() oder mavenCentral() bleiben unverändert.

Android: Kotlin und configChanges

Wenn dein App-Modul Kotlin nutzt, setze kotlin_version = '2.2.20'. Kotlin 2.x macht den alten kotlinOptions {} Block zu einem Fehler, also verschiebe jvmTarget in kotlin { compilerOptions { ... } }.

Dann füge density zur MainActivity hinzu, damit die WebView bei Änderungen der Displaydichte (Foldables, Fenstergrößenänderung, Einstellungen der Displaygröße) nicht neu erstellt wird:

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

Android: das Bridge-Layout wurde umbenannt

bridge_layout_main.xml existiert nicht mehr. Wenn dein MainActivity oder ein benutzerdefiniertes Fragment auf R.layout.bridge_layout_main nutze R.layout.capacitor_bridge_layout_main.

Edge-to-Edge und das neue System Bars Plugin

Dies ist die Änderung, die sich am ehesten visuell bemerkbar macht. Capacitor 8 hat android.adjustMarginsForEdgeToEdge entfernt und ein Core System Bars Plugin hinzugefügt. Du musst es nicht installieren, es wird mitgeliefert @capacitor/core.

Android 15 erzwingt Edge-to-Edge für Apps, die auf SDK 35 abzielen, und Android 16 entfernt das Opt-out für Apps, die auf SDK 36 abzielen. Capacitor 8 zielt auf 36 ab, daher wird Ihr Web-Content jetzt hinter Status- und Navigationsleiste gezeichnet, wenn Sie die Insets nicht behandeln.

Die Plugin-Konfiguration liegt unter 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;

Mit css oder native, neuere Android-WebViews (Chromium 140+) respektieren viewport-fit=cover und melden echte env(safe-area-inset-*) Werte. Auf älteren WebViews versieht Capacitor die WebView mit Padding und setzt die Env-Werte auf 0px. Setze das Meta-Tag und nutze die Variablen:

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

Zur Laufzeit kannst du den Bar-Stil oder die Sichtbarkeit ändern:

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

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

Apps mit Ionic Framework nutzen bereits die safe-area-Variablen, daher reicht in der Regel das Meta-Tag. Unser älterer Beitrag zu edge-to-edge ohne Plugins beschreibt die Capacitor 7-Option, die es in 8 nicht mehr gibt.

Weitere Verhaltensänderungen zum Prüfen

• appendUserAgent unter iOS: Capacitor 7 fügte zwei Leerzeichen vor deinem String hinzu, Capacitor 8 fügt eines hinzu. Wenn dein Server den User-Agent strikt parst, füge ein führendes Leerzeichen zu ios.appendUserAgent (nicht die Root-Option, die auch Android betrifft).
• Screen Orientation und Barcode Scanner: Auf großen Bildschirmen mit Android 16+ werden Orientierungssperren ignoriert. Ein temporärer Opt-out ist über die android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY Manifest-Property möglich, aber Android 17 entfernt sie.
• Geolocation: timeout gilt nun für alle Requests auf Android und iOS. Falls neue Timeouts auftreten, erhöhe den Wert. watchPosition auf Android erhielt eine interval Option.
• Statusleiste: Das Plugin liefert keine eigenen CAPBridgeViewController Notification-Dateien mehr mit, da der Core diese Events jetzt selbst auslöst.
• Neue iOS-Plattformen nutzen standardmäßig SPM: bunx cap add ios erstellt jetzt ein SPM-Projekt. Verwende --packagemanager CocoaPods falls du das alte Template benötigst. Siehe die Nutzung von CocoaPods mit Capacitor 8.

Upgrade überprüfen

Gehe diese Liste auf beiden Plattformen durch, bevor du publishst:

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

• cap doctor zeigt passende 8.x-Versionen für Core, CLI, iOS und Android an.
• Die App startet, der Splash-Screen verschwindet, Deep Links öffnen den richtigen Screen.
• Statusleiste und Navigationsleiste sehen auf einem Android-15/16-Gerät und einem iPhone mit Notch korrekt aus.
• Push-Benachrichtigungen, Kamera, Dateizugriff und alle Plugins mit nativen Berechtigungen funktionieren weiterhin.
• Ein Release-Build (Archive in Xcode, ./gradlew bundleRelease) ist erfolgreich, nicht nur Debug.

Wenn du nicht auf jedem Rechner Xcode 26 und JDK 21 pflegen willst, Capgo Build führt die iOS- und Android-Builds in der Cloud mit aktuellen Toolchains aus.

Veröffentliche das Upgrade sicher mit Live Updates

Ein Capacitor-Major-Upgrade ändert native code, daher muss es über den App Store und Google Play. Web-Bundles, die nach dem Upgrade gebaut werden, können Plugin-APIs aufrufen, die ältere Binaries nicht haben.

Wenn du Capgo Live Updates, trenne Capacitor 7-Nutzer und Capacitor 8-Nutzer, bis die Adoption aufgeholt hat: Erhöhe deine Native-Version, lade neue Bundles in einen Channel hoch, der vom neuen Binary verwendet wird, und führe aus Compatibility Check bevor du hochlädst:

bunx @capgo/cli@latest bundle compatibility

Es vergleicht die Native-Plugin-Versionen in deinem Bundle mit denen, die auf dem Channel laufen, und markiert Abweichungen, bevor Nutzer ein defektes Update erhalten.

Häufige Capacitor 8-Upgrade-Fehler beheben

The engine "node" is incompatible oder das CLI weigert sich zu starten. Du nutzt Node 20 oder älter. Installiere Node 22 LTS und aktualisiere auch dein CI-Image.

error: invalid source release: 21 auf Android. Gradle läuft mit JDK 17. Weise Android Studio auf das mitgelieferte JDK 21 hin (Einstellungen > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK) und festlegen JAVA_HOME auf JDK 21 für Command-Line- und CI-Builds.

Minimum supported Gradle version is 8.13. Du hast AGP aktualisiert, aber nicht den Wrapper. Setze den Wrapper auf 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion ist irgendwo noch 35. Prüfe variables.gradle und jedes Plugin, das es hartkodiert.

Using 'kotlinOptions' ... is an error oder ähnliche Kotlin-DSL-Fehler. Ein Plugin oder dein App-Modul nutzt noch kotlinOptions. Aktualisiere das Plugin oder patche es, bis ein Release erscheint (siehe wie man ein Capacitor-Plugin patcht).

Xcode: No such module 'Capacitor' nach dem Upgrade. Für CocoaPods öffne App.xcworkspace, nicht App.xcodeproj, and rerun bunx cap sync ios. Für SPM nutze File > Packages > Reset Package Caches.

"X" plugin is not implemented on ios/android. Das Plugin wurde nicht synchronisiert oder es gibt kein Capacitor 8 / SPM-kompatibles Release. Führe bunx cap sync aus und lies die Warnungen.

Für eine längere Liste siehe die Capacitor iOS-Troubleshooting-Guide und Android-Fehlerbehebung. Unvereinbare Core- und Plugin-Versionen werden in Capacitor Versions-Mismatch-Fehler beheben.

Let an AI agent do the boring parts

Wenn du Claude Code, Cursor oder einen ähnlichen Agenten verwendest, die offenen Capgo Skills einschließen capacitor-app-upgrade-v7-to-v8 und capacitor-app-upgrades für Major-Versionssprünge. Installiere sie mit bunx skills add Cap-go/capgo-skills und bitte den Agenten, die App zu upgraden. Er führt den Migrator aus und prüft dann die Schritte, die CLI normalerweise übersieht, wie z. B. Gradle-Syntax, Kotlin-Optionen und CI-Images.

Was kommt als Nächstes

Capacitor 9 ist bereits im Prerelease. Sobald du auf 8 stabil bist, lies Vorbereitung auf Capacitor 9 damit das nächste Upgrade kleiner ausfällt.