Vorbereitung auf Capacitor 9: Was App- und Plugin-Teams jetzt tun können

Capacitor 9 ist auf der next dist-tag verfügbar, während es auf die allgemeine Verfügbarkeit hinarbeitet. Du musst deine App nicht sofort beim Alpha-Release upgraden, aber der offizielle Capacitor 9 Update-Guide und Plugin-Update-Guide bereits die Schwachstellen der Toolchain und API Entfernungen aufgezeigt, die man frühzeitig angehen sollte.

Dieser Artikel ist eine Vorbereitungs- Checkliste: Aufgaben, die du bereits in Capacitor 8 (oder in einem Branch) erledigen kannst, damit der spätere bunx cap migrate Migration reibungslos statt schmerzhaft verläuft. Wenn du bereit für den Wechsel bist, folge den oben verlinkten Ionic-Guides Schritt für Schritt.

Toolchain- und Plattform-Einschränkungen (Apps)

Plane deine CI, lokalen Maschinen und Store-Pipelines basierend auf diesen Mindestanforderungen:

Wenn du unter iOS noch Capacitor 8.4 oder früher nutzt, benötigst du zusätzlich den UIScene Lifecycle aus dem Capacitor 8.5 Update vor Cap 9 — Xcode 27 setzt diesen voraus. Apps, die bereits auf 8.5 sind, können diesen Schritt überspringen.

Unter iOS lehnt Swift 6 (mit Xcode 27) @UIApplicationMain; beim Upgrade musst du es durch @main in AppDelegate.swift ersetzen, wie im offiziellen Guide beschrieben.

Cordova zum Zeitpunkt des App-Syncs (kein Plugin-Vorbereitungsschritt)

In Capacitor 9 wird der Cordova-Kompatibilitätsschicht nur dann in deine App eingebunden, wenn cap sync ein installiertes Cordova-Plugin erkannt wird. Android entfernt die extra Gradle-Module, wenn keine vorhanden sind; iOS hört auf, Einträge CapacitorCordova in das Podfile einzufügen oder Package.swift wenn keine vorhanden sind.

Das ist eine App-Ebene 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 oder ein Fork eines Plugins) Cordova-Symbole importiert, ohne dass ein echtes Cordova-Plugin im Projekt ist — diese Referenzen schlagen fehl, sobald die optionale Cordova-Einbindung 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, statt sie mitzuschleppen: Die meisten sind vor AGP 10 deprecated, und einige verhindern Cap 9 Builds (z. B. android.builtInKotlin=false deaktiviert die in AGP 9 enthaltene Kotlin-Unterstützung, und android.sdk.defaultTargetSdkToCompileSdkIfUnset=false verhindert, dass AGP automatisch erkennt targetSdkVersion).

Beachte bei der Migration auch Folgendes:

• Erhöhen variables.gradle Minimums (compile/target SDK 37, minSdkVersion 26, aktualisierte AndroidX-Versionen — siehe offizielle Doku).
• Explizite Angaben entfernen targetSdkVersion aus der App build.gradle damit AGP 9 dies ableiten kann aus compileSdkVersion.
• Deklarieren variables.gradle Symbole am Anfang von app/build.gradle (Gradle 9.6 markiert den impliziten Lookup vom Root-Projekt als deprecated).
• Standard-ProGuard-Dateinamen ändern, migrieren core-ktx zu androidx.core:core 1.19.0+, Nutzung des standalone Kotlin Gradle Plugins einstellen und entfernen jcenter().

Diff-Hunks kannst du hier lesen: Update auf 9.0 Android-Abschnitt und die gleichen Cleanups in einem Branch durchführen, bevor Capacitor Versionen aktualisiert werden.

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 Option „presentation“ wurde entfernt. Verwende banner und/oder list in deinen Presentation-Optionen.

Splash Screen (Android): Standard launchFadeOutDuration ändert sich von 200 ms auf 0. Wenn du dich auf das Ausfaden von Glitches beim ersten Paint verlassen hast, setze launchFadeOutDuration: 200 explizit in capacitor.config , bis ihr euer Startup-UI angepasst habt.

Prüft die Plugin-Abschnitte im 9.0 Update Guide auf AndroidX- und Google Play Services-Versionen, die mit euren offiziellen Plugins verknüpft sind.

Plugin-Maintainer: Bereitet euch auf Cap 9 vor, ohne Cap 8 zu brechen

Wenn ihr Capacitor Plugins nutzt, die auf Capacitor 8 basieren und Willst du code für Cap 9 bereit machen? Konzentriere dich auf die Entfernung veralteter API, nicht auf Packaging-Änderungen für Cap 9.

Das ist sicher, solange Cap 8 noch unterstützt wird:

• Ersetze @NativePlugin mit @CapacitorPlugin und migriere Legacy Permission / Activity-Result APIs zu @PermissionCallback / @ActivityCallback Mustern (siehe die Plugin 9.0 Guide Tabelle).
• Entferne PluginCall.hasOption, Plugin.getConfigValue, alt CapConfig Konstruktoren und Getter, PluginCall.save() / isSaved(), sowie weitere Java-Entfernungen unter „Breaking changes in code“.
• Unter iOS solltest du die CAPBridge Compatibility-Klasse und die veralteten CAPBridgeProtocol Helfer; verwenden ApplicationDelegateProxy, typisierte PluginCall Accessors und Bridge-Properties aus der Migrationstabelle.
• Ausführen bunx @capacitor/plugin-migration-v8-to-v9@latest auf einem Branch und behalte nur die API Edits, die mit den Cap 8 Peer-Dependencies kompilieren, bis du ein Major-Release für Cap 9 veröffentlichst.

Entferne nicht das Cordova SPM-Produkt aus deinem Plugin Package.swift solange ihr Capacitor 8 noch unterstützt. Cap 8 Projekte erwarten diese Abhängigkeit, wenn dein Plugin auf SPM basiert; ein vorzeitiges Entfernen würde Nutzer beeinträchtigen, die noch auf Version 8 sind. Behandle optionale Cordova / das Entfernen der bedingungslosen Cordova Produkt als eine Capacitor nur für Version 9 Release-Line (oder eine explizit dokumentierte SemVer-Major-Version für Cap 9+), sobald ihr den Support für Cap 8 einstellt – wie im Plugin-Guide beschrieben, nicht als Vorbereitung innerhalb der Cap 8 Line.

Dieselbe Faustregel gilt für das Bumping von capacitor-swift-pm zu 9.0.0-alpha.x in Package.swift: das gehört in deine Cap 9 Major-Version, nicht in ein Cap-8-kompatibles Release.

Capgo Live Updates und den nativen Cap 9 Store Build

Capgo liefert Web-Bundle OTA-Updates; der native Shell stammt weiterhin aus dem App Store oder Google Play. Wenn du deine App auf Capacitor 9 aktualisierst:

1. Ausliefern mindestens ein Store-Build gegen Capacitor 9 Native-Projekte (iOS und Android) kompiliert wurde. Diese Binary bildet die native Baseline, auf die Capgo Channels abzielen.
2. Erst wenn dieser Build bei den Usern ist, solltest du dich auf OTA-Bundles verlassen, die gegen das Cap 9 WebView- und Plugin-Verhalten getestet wurden.
3. Setze Production-Channels auf die metadata Strategie und lade das passende Cap 9 Bundle für jeden Channel mit --auto-min-update-versionhoch. Für diesen gezielten Native-Baseline-Upload lass --fail-on-incompatible weg (native Packages sollten sich nicht ändern). Behalte --fail-on-incompatible und --auto-min-update-version auf tägliche OTA-Uploads danach. Siehe Native + OTA Channel Workflow.
4. Halte Channel und Semver-Regeln synchron, damit du nie ein Bundle pushst, das Cap 9 APIs voraussetzt, während auf den Geräten noch ein älterer Native Build läuft.

Wenn du Capgo Build oder deine eigene CI nutzt, aktualisiere die Agents bevor den Cap 9 Store-Release, damit die Pipeline mit dem übereinstimmt, was die Nutzer installieren: macOS Runner benötigen Node 24+ und Xcode 27+; Linux Runner benötigen Node 24+ und Android-Tools, die mit AGP 9.2.1 / Gradle 9.5.1 kompatibel sind (Xcode ist nur auf macOS verfügbar).

Empfohlene Reihenfolge

1. Installierte Tools aktualisieren auf CI-Hosts und Dev-Maschinen auf die oben genannten Versionen (Node, Xcode, Android Studio, JDK). Nicht die AGP-Abhängigkeit, den Gradle-Wrapper oder andere Android-Projektdateien der Cap 8 App auf Cap 9 Werte anheben, bis bunx cap migrate — diese Änderungen zum Migrationsschritt gehören.
2. Deprecated native APIs fixen in der App code und in Plugins (besonders bei Custom- AppDelegate URL-Handling und Android-Bridge-Nutzung).
3. Android Gradle-Dateien bereinigen Dateien und Skripte (gradle.properties, ProGuard-Defaults, --url in Dev-Skripten).
4. Cordova-Nutzung prüfen Nutzung auf App-Ebene; ändern Sie Plugin-SPM- oder Cordova-Produkte erst mit den reinen Cap 9-Releases.
5. Sobald Cap 9 GA ist (oder wenn Sie next), führen Sie bun add -d @capacitor/cli@next (oder @latest nach dem Release), dann bunx cap migrate, und folgen Sie Update auf 9.0.
6. Veröffentliche den Cap 9 Native Build in den Stores, um dann Capgo OTA-Rollouts auf dem passenden Channel fortzusetzen oder zu erweitern.

Capacitor 9 konzentriert sich primär darauf, „Deprecations abzubauen und die Ausrichtung an modernen Android- und Apple-Toolchains zu optimieren“. Diese Arbeit bereits in Cap 8 zu erledigen, hält den Upgrade-Diff klein und sorgt dafür, dass deine Plugins mit Teams kompatibel bleiben, die heute noch 8.x ausliefern.