Capacitor 9 ist verfügbar auf next dist-tag, während es in Richtung allgemeine Verfügbarkeit geht. Du musst deine App nicht am Tag des Alpha-Releases upgraden, aber der offizieller Capacitor 9 Update-Guide und Plugin-Update-Guide bereits die Toolchain-Mindestanforderungen und die API-Entfernungen aufführen, die man frühzeitig angehen sollte.
Dieser Artikel ist eine Vorbereitungs- Checkliste: Aufgaben, die du schon auf Capacitor 8 (oder in einem Branch) erledigen kannst, damit der spätere bunx cap migrate Umstieg langweilig statt schmerzhaft wird. Wenn du bereit für den Wechsel bist, folge den oben verlinkten Ionic-Guides Zeile für Zeile.
Toolchain- und Plattform-Mindestanforderungen (Apps)
Richte deine CI, deine lokalen Maschinen und deine Store-Pipelines an diesen Mindestanforderungen aus:
| Bereich | Capacitor 9 Voraussetzung |
|---|---|
| Node.js | 24+ (aktuellste LTS empfohlen; npm 11 kommt mit Node 24) |
| Xcode | 27+ |
| iOS Deployment Target | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle Wrapper | 9.5.1 |
Wenn du für iOS noch auf Capacitor 8.4 oder älter bist, brauchst du zusätzlich das UIScene-Lifecycle aus dem Capacitor 8.5-Update vor Cap 9 – Xcode 27 erwartet es. Apps, die bereits auf 8.5 sind, können diesen zusätzlichen Schritt überspringen.
Auf iOS lehnt Swift 6 (mit Xcode 27) @UIApplicationMainab; beim Upgrade ersetzt du es durch @main in einem AppDelegate.swift wie im offiziellen Guide beschrieben.
Cordova beim App-Sync (kein Plugin-Prep-Schritt)
In Capacitor 9 ist die Cordova-Kompatibilitätsschicht nur in Ihre App eingebunden, wenn cap sync ein installiertes Cordova-Plugin erkennt. Android entfernt die zusätzlichen Gradle-Module, wenn keine vorhanden sind; iOS hört auf, CapacitorCordova in die Podfile oder Package.swift hinzuzufügen, wenn keine vorhanden sind.
Das ist eine App-Ebene hinzu Verhaltensänderung nach dem Upgrade. Solange du noch auf Cap 8 bist, musst du Cordova nicht vorab aus deinem Template entfernen. Prüfe jedoch, ob eigene native code (deine eigenen oder ein geforktes Plugin) Cordova-Symbole importieren, ohne dass ein tatsächliches Cordova-Plugin im Projekt vorhanden ist – diese Referenzen werden fehlschlagen, sobald die optionale Cordova-Anbindung greift.
Android: gradle.properties und AGP-9-Standardeinstellungen
Der AGP Upgrade Assistant schreibt oft explizite gradle.properties Flags, damit Builds das AGP-8-Verhalten beibehalten. Capacitor 9 Apps sollten entfernen diese Einträge entfernen, statt sie mitzuschleppen: Die meisten sind vor AGP 10 deprecated, und einige brechen Cap-9-Builds (zum Beispiel android.builtInKotlin=false deaktiviert die Kotlin-Unterstützung, die AGP 9 mitbringt, und android.sdk.defaultTargetSdkToCompileSdkIfUnset=false verhindert, dass AGP Werte ableitet targetSdkVersion).
When you migrate, also expect to:
- Erhöhen
variables.gradleMindestwerte (compile/target SDK 37,minSdkVersion26, aktualisierte AndroidX-Versionen – siehe offizielles Dokument). - Explizite Angabe entfernen
targetSdkVersionaus der Appbuild.gradledamit AGP 9 es daraus ableiten kanncompileSdkVersion. - Deklarieren
variables.gradleSymbole am Anfang vonapp/build.gradle(Gradle 9.6 stuft den impliziten Lookup aus dem Root-Projekt als veraltet ein). - Standard-ProGuard-Dateinamen tauschen, migrieren
core-ktxzuandroidx.core:core1.19.0+, die Nutzung des standalone Kotlin Gradle Plugins einstellen und entfernenjcenter().
Du kannst die Diff-Hunks im Update auf 9.0 Android-Abschnitt lesen und wende dieselben Cleanups in einem Branch an, bevor du die Capacitor-Versionen bumpst.
CLI: cap run --url
Capacitor 9 fasst die live-reload-Flags für host/port/https in einem einzigen --url Argument zusammen. Statt:
bunx cap run android -l --host 192.168.1.181 --port 5173
Übergib die URL, die dein Dev-Server ausgibt:
bunx cap run android --url http://192.168.1.181:5173/
Aktualisiere jetzt deine Skripte und README-Snippets, damit dein Muscle Memory nach dem Upgrade nicht gegen das neue CLI arbeitet.
Offizielle Plugins: Fallstricke bei Push und Splash
Zwei nutzerseitige Änderungen treten in Production-Apps oft auf:
Push-Benachrichtigungen (iOS): Die veraltete alert Die Präsentationsoption wurde entfernt. Verwenden banner und/oder list in deinen Presentation-Optionen.
Splash Screen (Android): Standard launchFadeOutDuration Änderungen von 200 ms auf 0. Wenn Sie sich auf das Fade-out verlassen haben, um erste Renderfehler zu verbergen, launchFadeOutDuration: 200 explizit in capacitor.config bis Sie Ihre Start-UI angepasst haben.
Suche in den Plugin-Abschnitten der 9.0-Update-Anleitung nach AndroidX- und Google Play Services-Versions-Bumps, die mit den offiziellen Plugins zusammenhängen, die du verwendest.
Plugin-Maintainer: Auf Cap 8 vorbereiten, ohne Cap 8 zu brechen
Wenn du Capacitor-Plugins auslieferst, die auf Capacitor 8 genutzt werden, und und ein Cap-9-taugliches code willst, konzentriere dich auf die Entfernung veralteter API, nicht auf Cap-9-spezifische Packaging-Änderungen.
Sicher durchzuführen, solange Cap 8 unterstützt wird:
- Ersetze
@NativePluginmit@CapacitorPluginund migriere die Legacy-Permission-/Activity-Result-APIs auf@PermissionCallback/@ActivityCallbackMuster (siehe Plugin-9.0-Guide Tabelle). - Entfernen
PluginCall.hasOption,Plugin.getConfigValue, alteCapConfigKonstruktoren und Getter,PluginCall.save()/isSaved()sowie weitere entfernte Java-Elemente, die unter „Breaking changes in code“ aufgeführt sind. - Auf iOS die Verwendung der
CAPBridgeKompatibilitätsklasse und die veraltetenCAPBridgeProtocolHelper nicht mehr nutzen; nutzeApplicationDelegateProxy, typisiertePluginCallAccessors und Bridge-Properties aus der Migrations-Tabelle beenden. - Ausführen
bunx @capacitor/plugin-migration-v8-to-v9@latestauf einem Branch und behalte nur die API-Änderungen bei, die noch gegen die Cap 8 Peer Dependencies kompilieren, bis du eine Major-Version für Cap 9 veröffentlichst.
Entferne nicht das Cordova SPM-Produkt aus deinem Plugin Package.swift solange du noch Capacitor 8 unterstützt. Cap 8-Projekte erwarten diese Abhängigkeit, wenn dein Plugin SPM-basiert ist; ein frühes Entfernen bricht Konsumenten, die noch auf 8 sind. Behandle optional Cordova / Entfernen der bedingungslosen Cordova Produkt als eine Capacitor 9-only Release-Zweig (oder ein semver-Major, der explizit als Cap 9+ dokumentiert ist), nachdem du die Unterstützung für Cap 8 einstellst – wie im Plugin-Guide beschrieben, nicht als Vorbereitungsarbeit auf dem Cap-8-Zweig.
Dieselbe Faustregel gilt für das Bumpen capacitor-swift-pm zu 9.0.0-alpha.x in einem Package.swift: Das gehört in deine Cap-9-Major-Version, nicht in ein Cap-8-kompatibles Release.
Capgo Live Updates und der native Cap-9-Store-Build
Capgo liefert Web-Bundle Updates over the air; die native Shell kommt weiterhin aus dem App Store und Google Play. Wenn du deine App auf Capacitor 9 migrierst:
- Ausliefern mindestens ein Store-Build kompiliert gegen Capacitor 9 native Projekte (iOS und Android). Diese Binärdatei bildet die native Baseline, auf die die Capgo Kanäle abzielen.
- Erst wenn dieser Build bei den Nutzern ist, solltest du dich auf OTA-Bundles verlassen, die gegen das Cap-9-WebView- und Plugin-Verhalten getestet wurden.
- Stellt Produktionskanäle auf die
metadataStrategie ein und ladet das passende Cap 9-Bundle in jeden Kanal mit--auto-min-update-versionhoch. Für diesen bewussten nativen Baseline-Upload lasst--fail-on-incompatibleweg (native Pakete sollen sich ändern). Behaltet--fail-on-incompatibleund--auto-min-update-versionbei alltäglichen OTA-Uploads danach bei. Siehe Native + OTA-Channel-Workflow. - Halte Channel- und Semver-Regeln synchron, damit du nie ein Bundle pushst, das Cap-9-APIs annimmt, auf Geräte, die noch eine ältere Native-Shell ausführen.
Wenn du Capgo Build oder dein eigenes CI, aktualisiere die Agents bevor den Cap-9-Store-Release, damit die Pipeline dem entspricht, was Nutzer installieren: macOS Runners benötigen Node 24+ und Xcode 27+; Linux Runners benötigen Node 24+ und Android-Tooling, das mit AGP 9.2.1 / Gradle 9.5.1 (Xcode ist nur für macOS verfügbar).
Empfohlene Reihenfolge der Schritte
- Installiertes Tooling upgraden auf CI-Hosts und Entwickler-Maschinen auf die Mindestversionen oben (Node, Xcode, Android Studio, JDK). Nicht Cap 8-App-AGP-Abhängigkeit, Gradle-Wrapper oder andere Android-Projektdateien auf Cap 9-Werte hochstufen, bis
bunx cap migrate— diese Projektänderungen gehören zum Migrations-Schritt. - Nicht mehr unterstützte native APIs beheben in der App code und in Plugins (insbesondere Custom-
AppDelegateURL-Verarbeitung und Android-Bridge-Nutzung). - Android-Gradle aufräumen Dateien und Skripte (
gradle.properties, ProGuard-Standardwerte,--urlin Dev-Skripten). - Cordova-Nutzung Nutzung auf App-Ebene; ändere die SPM- und Cordova-Plugin-Produkte nicht, bis die nur für Cap 9 vorgesehenen Releases erscheinen.
- Wenn Cap 9 GA ist (oder wenn du
next), runbun add -d @capacitor/cli@next(oder@latestnach dem Release aus, dannbunx cap migrate, und folge Update auf 9.0. - Cap 9 Native Build veröffentlichen an die Stores, dann Capgo OTA-Rollouts auf dem passenden Channel fortsetzen oder ausbauen.
Capacitor 9 bedeutet vor allem, Deprecations abzubauen und sich an moderne Android- und Apple-Toolchains anzupassen. Diese Arbeit in Cap 8 zu erledigen, hält den Upgrade-Diff klein und die Plugins kompatibel mit Teams, die heute noch 8.x ausliefern.