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

Capacitor 9 is available on the next dist-tag während es sich auf die allgemeine Verfügbarkeit zubewegt. Sie müssen Ihre App nicht am Tag, an dem die Alpha-Version verfügbar wird, aktualisieren, aber official Capacitor 9 update guide und Leitfaden für die Plugin-Update-Installation bereits die Werkzeuge der Toolchain und API-Entfernungen, die sich frühzeitig angehen lassen.

Dieser Artikel ist ein Vorbereitung Arbeitsliste: Dinge, die Sie auf Capacitor 8 (oder auf einem Zweig) tun können, um die spätere bunx cap migrate pass ist langweilig anstatt schmerzhaft. Wenn Sie bereit sind, zu übernehmen, folgen Sie den Anleitungen von Ionic, die oben in der Zeile angegeben sind.

Toolkette und Plattformböden (Apps)

Planen Sie Ihre CI, lokale Maschinen und Speicherpipelines um diese Mindestanforderungen herum:

If Sie noch auf Capacitor 8.4 oder früher für iOS sind, benötigen Sie auch das UIScene-Lebenszyklus Arbeiten Sie aus der 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 wird Swift 6 (mit Xcode 27) abgelehnt @UIApplicationMain; wenn Sie aktualisieren, ersetzen Sie es durch @main in AppDelegate.swift wie in der offiziellen Anleitung beschrieben.

Cordova zu App-Synchronisierungszeit (kein Plugin-Vorbereitungsschritt)

In Capacitor 9 ist der Cordova-Kompatibilitätslayer nur in Ihr App eingebunden, wenn cap sync einen installierten Cordova-Plugindetektieren kann. Android entfernt die zusätzlichen Gradle-Module, wenn keine anwesend sind; iOS stoppt das Hinzufügen CapacitorCordova zum Podfile oder Package.swift wenn keiner vorhanden ist.

Das ist ein Anwendungslevel Verhaltensänderung nach dem Upgrade. Während Sie noch auf Cap 8 sind, müssen Sie den Cordova nicht vorzeitig aus Ihrem Template entfernen. Führen Sie eine Überprüfung durch, ob es in Ihrem Projekt benutzerdefinierte native code Cordova-Symbole ohne einen tatsächlichen Cordova-Plugin importieren – diese Referenzen werden fehlschlagen, sobald die optionalen Cordova-Verbindungen gelten.

Android: gradle.properties und AGP 9 Standards

Der AGP-Upgrade-Assistent schreibt oft explizite gradle.properties Flaggen, damit die Builds das Verhalten von AGP 8 beibehalten. Capacitor 9-Apps sollten entfernen Stattdessen diese Einträge aufheben, anstatt sie fortzuführen: Die meisten sind vor AGP 10 abgeschafft und einige brechen die Builds von Cap 9 (z.B. android.builtInKotlin=false deaktiviert die Unterstützung für Kotlin, die AGP 9 enthält, und android.sdk.defaultTargetSdkToCompileSdkIfUnset=false stoppt AGP von der Inferenz targetSdkVersion).

Wenn Sie migrieren, erwarten Sie auch:

• Bump variables.gradle Minimums (Kompilierziel SDK 37, minSdkVersion 26, aktualisierte AndroidX-Versionen – siehe die offizielle Dokumentation).
• Entfernen Sie explizite targetSdkVersion aus der App build.gradle so dass AGP 9 sie von selbst ermitteln kann compileSdkVersion.
• Erklären Sie variables.gradle Symbolen an der Spitze app/build.gradle (Gradle 9.6 deprecates die implizite Suche vom Root-Projekt).
• Ersetzen Sie die Standard-ProGuard-Dateinamen, migrieren Sie core-ktx zu androidx.core:core 1.19.0+, Abmelden von der standalone Kotlin Gradle-Plugin-Nutzung und entfernen jcenter().

Sie können die Differenzhunks in der Update auf 9.0 Android-Sektion und wenden Sie die gleichen Reinigungen auf einem Zweig an, bevor Sie die Capacitor-Versionen erhöhen.

CLI: cap run --url

Capacitor 9 vereint die Flags für live-reload-Host/Port/HTTPS in einem einzigen Argument. Anstatt: --url Argument. Anstatt:

bunx cap run android -l --host 192.168.1.181 --port 5173

pass the URL your dev server prints:

bunx cap run android --url http://192.168.1.181:5173/

Aktualisieren Sie Skripte und README-Snippets jetzt, damit die neue CLI nach dem Upgrade nicht gegen die Gewohnheiten kämpfen muss.

Offizielle Plugins: push- und splash-Geheimnisse

Zwei Benutzerfunktionen treten oft in Produktionsanwendungen auf:

Benachrichtigungen (iOS): Die veraltete alert Präsentationsoption wird entfernt. Verwenden Sie banner und/oder list in Ihren Präsentationsoptionen.

Splash-Screen (Android): Standard launchFadeOutDuration ändert sich von 200 ms aufWenn Sie sich auf die Fade-Effekte verlassen haben, um erste Paint-Glitches zu verbergen, launchFadeOutDuration: 200 explizit in capacitor.config bis Sie Ihre Startseite anpassen.

Scannen Sie die Pluginbereiche in der 9.0 Aktualisierungsanleitung für AndroidX und Google Play Services Versionssprünge, die mit offiziellen Plugins verbunden sind, die Sie verwenden.

Plugin-Hersteller: Bereiten Sie sich auf Cap 8 vor, ohne Cap 8 zu brechen

Wenn Sie Capacitor-Plugins bereitstellen, die auf Capacitor 8 und wollen Sie ein Cap 9-geeignetes code, sich auf veraltet API Entfernungdie Entfernung veralteter __CAPGO_KEEP_0__

Sicher zu tun, solange Cap 8 unterstützt wird:

• Ersetzen @NativePlugin durch @CapacitorPlugin und migrieren Sie die Legacy-Berechtigungs- / -Aktivitätsresultat-APIs zu @PermissionCallback / @ActivityCallback Mustern (siehe das Plugin 9.0-Leitfaden Tabelle).
• Entfernen PluginCall.hasOption, Plugin.getConfigValue, alte CapConfig Konstruktoren und Getter, PluginCall.save() / isSaved(), und andere Java-Entfernungen, die unter „Zuverlässigkeitsänderungen in code“ aufgeführt sind.
• Auf iOS, stoppen Sie die Verwendung der CAPBridge Kompatibilitätsklasse und veralteten CAPBridgeProtocol Hilfen; verwenden ApplicationDelegateProxy, getippt PluginCall Zugriffsanbieter und Brücken-Eigenschaften aus der Migrationstabelle.
• Ausführen bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

Entfernen Sie nicht das Cordova SPM-Produkt aus Ihrem Plugin's Package.swift während Sie noch Capacitor 8 unterstützen. Cap 8-Projekte erwarten diese Abhängigkeit, wenn Ihr Plugin SPM-basiert ist; das Frühzeitige Entfernen bricht die auf 8 noch verbleibenden Verbraucher. optional Cordova / Entfernen der unbedingten Cordova product Produkt als Capacitor 9-only release line (or a semver major explicitly documented as Cap 9+), after you stop supporting Cap 8 — as described in the plugin guide, not as prep work on the Cap 8 line.

Die gleiche Regel gilt für die Erhöhung capacitor-swift-pm bis 9.0.0-alpha.x in Package.swiftDass gehört auf Ihr Cap 9-Major, nicht auf eine Cap-8-kompatible Version.

Capgo Live-Updates und die native Cap 9 Store-Build

Capgo liefert Web-Bundle Updates über das Air; die native Shell kommt weiterhin aus dem App Store und Google Play. Wenn Sie Ihre App auf Capacitor 9 verschieben:

1. Ship zumindest eine Store-Build kompatibel mit Capacitor 9 nativen Projekten (iOS und Android) kompiliert. Diese Binärdatei stellt den nativen Ausgangspunkt Capgo für die Zielkanäle dar.
2. Nur nachdem der Build in den Händen der Benutzer ist, sollten Sie sich auf OTA-Bundles verlassen, die gegen Cap 9 WebView und Pluginverhalten getestet wurden.
3. Setzen Sie die Produktionskanäle auf die metadata Strategie und laden Sie das entsprechende Cap 9-Bundle auf jeden Kanal hoch. --auto-min-update-versionBei dieser gezielten nativen Ausgangsbasisupload omit --fail-on-incompatible (nativen Pakete sollten sich ändern). Halten Sie --fail-on-incompatible und --auto-min-update-version nach jedem alltäglichen OTA-Upload. Native + OTA-Kanal-Workflow.
4. Keep channel and semver rules aligned so you never push a bundle that assumes Cap 9 APIs to devices still running an older native shell.

Wenn Sie Capgo Build oder Ihre eigenen CI, Refresh-Agenten vorher Der Cap 9 Store-Release, sodass der Pipeline dem installierten Benutzer entspricht. macOS Laufarbeiter benötigen Node 24+ und Xcode 27+; Xcode 27+ Laufarbeiter benötigen Node 24+ und hosten Android-Tooling im Einklang mit Die Runner benötigen Node 24+ und die Android-Entwicklungstools müssen mit (Xcode ist nur für macOS verfügbar).

(Xcode ist macOS-spezifisch).

1. Installierte Werkzeuge aktualisieren auf CI-Hosts und Entwicklermaschinen auf die höheren Versionen (Node, Xcode, Android Studio, JDK). Tun nicht die AGP-Abhängigkeit, den Gradle-Wrapper oder andere Android-Projektdateien des Cap 8-Apps auf Cap 9-Werte anheben, bis bunx cap migrate — diese Projektaufgaben gehören zum Migrationsschritt.
2. Veraltete native APIs in App code und Plugins (insbesondere benutzerdefinierte) AppDelegate Reinigen Sie Android-Gradle-
3. Dateien und Skripte ( , ProGuard-Standardwerte,gradle.propertiesin Entwickler-Skripten). --url Upgrade installed tooling
4. Audit Cordova Verwenden Sie es auf der Anwendungsstufe; ändern Sie die Plugin-SPM Cordova-Produkte nicht, bis Cap 9-only-Ausgaben erscheinen.
5. Wenn Cap 9 GA (oder wenn Sie akzeptieren next), führen Sie bun add -d @capacitor/cli@next (oder @latest nach der Veröffentlichung) bunx cap migratenach der Veröffentlichung), dann , und folgen Sie.
6. Veröffentlichen Sie die native Cap 9-Build zu den Speichern, dann die Capgo OTA-Rollouts auf dem passenden Kanal fortsetzen oder erweitern.

Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.