Zum Hauptinhalt springen
Capacitor

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

Capacitor 9 setzt neue Maßstäbe bei Node, Xcode, Android Gradle und veralteten nativen APIs. So bereitest du dich auf Capacitor 8 vor, bevor du die Version wechselst – inklusive optionalem Cordova-Sync, CLI Live Reload und Capgo OTA-Store-Builds.

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

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.gradle Mindestwerte (compile/target SDK 37, minSdkVersion 26, aktualisierte AndroidX-Versionen – siehe offizielles Dokument).
  • Explizite Angabe entfernen targetSdkVersion aus der App build.gradle damit AGP 9 es daraus ableiten kann compileSdkVersion.
  • Deklarieren variables.gradle Symbole am Anfang von app/build.gradle (Gradle 9.6 stuft den impliziten Lookup aus dem Root-Projekt als veraltet ein).
  • Standard-ProGuard-Dateinamen tauschen, migrieren core-ktx zu androidx.core:core 1.19.0+, die Nutzung des standalone Kotlin Gradle Plugins einstellen und entfernen jcenter().

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 @NativePlugin mit @CapacitorPlugin und migriere die Legacy-Permission-/Activity-Result-APIs auf @PermissionCallback / @ActivityCallback Muster (siehe Plugin-9.0-Guide Tabelle).
  • Entfernen PluginCall.hasOption, Plugin.getConfigValue, alte CapConfig Konstruktoren und Getter, PluginCall.save() / isSaved()sowie weitere entfernte Java-Elemente, die unter „Breaking changes in code“ aufgeführt sind.
  • Auf iOS die Verwendung der CAPBridge Kompatibilitätsklasse und die veralteten CAPBridgeProtocol Helper nicht mehr nutzen; nutze ApplicationDelegateProxy, typisierte PluginCall Accessors und Bridge-Properties aus der Migrations-Tabelle beenden.
  • Ausführen bunx @capacitor/plugin-migration-v8-to-v9@latest auf 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:

  1. 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.
  2. 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.
  3. Stellt Produktionskanäle auf die metadata Strategie 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-incompatible weg (native Pakete sollen sich ändern). Behaltet --fail-on-incompatible und --auto-min-update-version bei alltäglichen OTA-Uploads danach bei. Siehe Native + OTA-Channel-Workflow.
  4. 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

  1. 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.
  2. Nicht mehr unterstützte native APIs beheben in der App code und in Plugins (insbesondere Custom- AppDelegate URL-Verarbeitung und Android-Bridge-Nutzung).
  3. Android-Gradle aufräumen Dateien und Skripte (gradle.properties, ProGuard-Standardwerte, --url in Dev-Skripten).
  4. Cordova-Nutzung Nutzung auf App-Ebene; ändere die SPM- und Cordova-Plugin-Produkte nicht, bis die nur für Cap 9 vorgesehenen Releases erscheinen.
  5. Wenn Cap 9 GA ist (oder wenn du next), run bun add -d @capacitor/cli@next (oder @latest nach dem Release aus, dann bunx cap migrate, und folge Update auf 9.0.
  6. 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.

Live-Updates für Capacitor-Apps

Wenn ein Bug im Web-Layer live ist, liefere den Fix über Capgo aus, statt Tage auf die App-Store-Freigabe zu warten. Nutzer bekommen das Update im Hintergrund, während native Änderungen im normalen Review-Prozess bleiben.

Neues aus unserem Blog

Capgo gibt dir die besten Insights, um eine wirklich professionelle Mobile App zu erstellen.