Capacitor 9 est disponible sur le next dist-tag pendant qu’il évolue vers la disponibilité générale. Vous n’avez pas à mettre à jour votre application le jour où l’alpha arrive, mais le guide officiel de la mise à jour Capacitor 9 et guide de mise à jour des plugins détaille déjà les failles de la toolchain et les suppressions de API qu'il vaut mieux traiter tôt.
Cet article est une préparation checklist : le travail que vous pouvez faire sur Capacitor 8 (ou sur une branche) pour que le passage bunx cap migrate final soit une formalité plutôt qu'une épreuve. Quand vous serez prêt à basculer, suivez les guides d'Ionic liés ci-dessus, ligne par ligne.
Toolchain et versions minimales de plateforme (apps)
Planifiez votre CI, vos machines locales et vos pipelines de store sur la base de ces minimums :
| Domaine | prérequis Capacitor 9 |
|---|---|
| Node.js | 24+ (dernière LTS recommandée ; npm 11 embarque Node 24) |
| Xcode | 27+ |
| Cible de déploiement iOS | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
Si vous êtes encore sur Capacitor 8.4 ou une version antérieure pour iOS, vous avez également besoin du cycle de vie UIScene depuis la mise à jour Capacitor 8.5 avant Cap 9 — Xcode 27 l’attend. Les apps déjà sur 8.5 peuvent passer cette étape supplémentaire.
Sur iOS, Swift 6 (avec Xcode 27) rejette @UIApplicationMain ; lors de la mise à niveau, remplacez-le par @main dans AppDelegate.swift comme décrit dans le guide officiel.
Cordova à la sync de l'app (pas une étape de préparation du plugin)
Dans Capacitor 9, la couche de compatibilité Cordova est n'est câblé dans votre application que lorsque cap sync détecte un plugin Cordova installé. Android supprime les modules Gradle supplémentaires s'il n'y en a aucun ; iOS cesse d'ajouter CapacitorCordova au Podfile ou Package.swift s'il n'y en a aucun.
Il s'agit d'un niveau de l'app changement de comportement après la mise à niveau. Tant que vous êtes encore sur Cap 8, vous n'avez pas besoin de retirer Cordova de votre template par précaution. Vérifiez toutefois si des code natifs personnalisés (les vôtres ou un plugin forké) importent des symboles Cordova sans plugin Cordova réel dans le projet — ces références échoueront dès que le câblage Cordova optionnel s'appliquera.
Android : gradle.properties et les valeurs par défaut d'AGP 9
L’Assistant de migration AGP écrit souvent des gradle.properties flags afin que les builds conservent le comportement d’AGP 8. Capacitor 9 apps should supprimer ces entrées plutôt que de les conserver : la plupart sont dépréciées avant AGP 10, et certaines cassent les builds Cap 9 (par exemple android.builtInKotlin=false désactive le support Kotlin que AGP 9 inclut, et android.sdk.defaultTargetSdkToCompileSdkIfUnset=false empêche AGP de déduire targetSdkVersion).
Lors de la migration, prévoyez également de :
- Incrémenter
variables.gradleminimums (compilation/cible SDK 37,minSdkVersion26, versions AndroidX à jour — voir la doc officielle). - Supprimez les
targetSdkVersionexplicites de l’appbuild.gradleafin qu'AGP 9 puisse l'inférer à partir decompileSdkVersion. - Déclarer
variables.gradleles symboles en haut deapp/build.gradle(Gradle 9.6 déprécie la recherche implicite depuis le projet racine). - Remplacer les noms de fichiers ProGuard par défaut, migrer
core-ktxversandroidx.core:core1.19.0+, supprimer l'utilisation du plugin Kotlin Gradle autonome et retirerjcenter().
Vous pouvez lire les hunks de diff dans le Mise à niveau vers 9.0 section Android et appliquer les mêmes nettoyages sur une branche avant d'augmenter les versions Capacitor.
CLI : cap run --url
Capacitor 9 fusionne les flags host/port/https du live reload en un seul --url argument. Au lieu de :
bunx cap run android -l --host 192.168.1.181 --port 5173
passez l'URL affichée par votre serveur de dev :
bunx cap run android --url http://192.168.1.181:5173/
Update scripts and README snippets now so muscle memory does not fight the new CLI after upgrade.
Plugins officiels : pièges push et splash
Deux changements côté utilisateur apparaissent souvent dans les apps en production :
Notifications push (iOS) : Le plugin déprécié alert presentation dépréciée est supprimée. Utilisez banner et/ou list dans vos options de présentation.
Splash Screen (Android) : Par défaut launchFadeOutDuration modifications par rapport à 200 ms à 0Si vous comptiez sur le fondu pour masquer les artefacts du premier rendu, définissez-le launchFadeOutDuration: 200 explicitement dans capacitor.config until you adjust your startup UI.
Parcouvez les sections consacrées aux plugins du guide de mise à jour 9.0 pour les montées de version AndroidX et Google Play Services liées aux plugins officiels que vous utilisez.
Mainteneurs de plugins : préparer sur Cap 8 sans casser Cap 8
Si vous publiez des plugins Capacitor utilisés sur Capacitor 8 et vous voulez préparer code pour Cap 9, concentrez-vous sur la suppression des API obsolètes, pas sur les changements de packaging propres à Cap 9.
Sans risque tant que Cap 8 reste pris en charge :
- Remplacer
@NativePluginpar@CapacitorPluginet migrez les anciennes API de permissions / activity-result vers@PermissionCallback/@ActivityCallbackles patterns (voir le tableau du guide du plugin 9.0 ). - Supprimer
PluginCall.hasOption,Plugin.getConfigValue, ancienCapConfigconstructeurs et getters,PluginCall.save()/isSaved(), et autres suppressions Java listées dans « Breaking changes in code ». - Sur iOS, cessez d'utiliser la
CAPBridgeclasse de compatibilité et lesCAPBridgeProtocolhelpers dépréciés ; utilisezApplicationDelegateProxy, typésPluginCallles accesseurs et les propriétés du bridge depuis le tableau de migration. - Exécutez
bunx @capacitor/plugin-migration-v8-to-v9@latestsur une branche et ne conservez que les modifications API qui compilent encore contre les peer dependencies de Cap 8 jusqu'à ce que vous publiiez une version majeure pour Cap 9.
Ne supprimez pas le Cordova produit SPM de votre plugin Package.swift tant que vous supportez encore Capacitor 8. Les projets Cap 8 attendent cette dépendance si votre plugin est basé sur SPM ; la supprimer trop tôt casse les utilisateurs encore sur la version 8. Traitez Cordova en option / suppression du Cordova produit comme uniquement pour Capacitor 9 une ligne de release (ou une version majeure semver explicitement documentée comme Cap 9+), une fois que vous ne supportez plus Cap 8 — comme décrit dans le guide du plugin, et non comme un travail de préparation sur la branche Cap 8.
La même règle s’applique à l’augmentation de capacitor-swift-pm vers 9.0.0-alpha.x dans Package.swift: cela relève de votre version majeure Cap 9, pas d’une release compatible Cap 8.
Capgo live updates et le build natif Cap 9 pour les stores
Capgo livre bundle web en OTA ; le shell natif vient toujours de l'App Store et de Google Play. Lorsque vous faites passer votre application à Capacitor 9 :
- Déployer au moins un build pour les stores compilé avec des projets natifs Capacitor 9 (iOS et Android). Ce binaire établit la base native que ciblent les canaux Capgo.
- Ce n’est que lorsque ce build est entre les mains des utilisateurs que vous devez vous fier aux bundles OTA testés avec le WebView et le comportement des plugins de Cap 9.
- Configurez les canaux de production sur la
metadatastratégie et envoyez le bundle Cap 9 correspondant à chaque canal avec--auto-min-update-version. Pour cet upload intentionnel de la base native, omettez--fail-on-incompatible(les packages natifs sont censés changer). Gardez--fail-on-incompatibleet--auto-min-update-versionsur les uploads OTA quotidiens par la suite. Voir Workflow canal natif + OTA. - Gardez les règles de canal et de semver alignées pour ne jamais envoyer un bundle qui suppose les API de Cap 9 sur des appareils encore équipés d’un shell natif plus ancien.
Si vous utilisez Build Capgo ou votre propre CI, mettez à jour les agents avant la release store de Cap 9 pour que le pipeline corresponde à ce que les utilisateurs installent : machine macOS les runners nécessitent Node 24+ et Xcode 27+; Linux les runners nécessitent Node 24+ et les outils Android hôte alignés avec AGP 9.2.1 / Gradle 9.5.1 (Xcode est uniquement disponible sur macOS).
Ordre des opérations suggéré
- Mettre à jour les outils installés sur les hôtes CI et les machines de développement aux versions minimales ci-dessus (Node, Xcode, Android Studio, JDK). Ne pas passer la dépendance AGP, le wrapper Gradle ou d'autres fichiers du projet Android de l'application Cap 8 aux valeurs Cap 9, jusqu'à
bunx cap migrate— ces modifications de projet font partie de l'étape de migration. - Corriger les API natives dépréciées dans l'application code et les plugins (en particulier le
AppDelegatetraitement des URL et l'utilisation du pont Android). - Nettoyer Android Gradle fichiers et scripts (
gradle.properties, valeurs par défaut de ProGuard,--urldans les scripts de dev). - Auditez l’utilisation de Cordova au niveau de l’app ; ne modifiez pas les produits SPM Cordova des plugins avant les releases exclusives à Cap 9.
- Lorsque Cap 9 est en GA (ou lorsque vous acceptez
next), exécutezbun add -d @capacitor/cli@next(ou@latestaprès la release), puisbunx cap migrate, et suivez Mise à niveau vers 9.0. - Publiez le build natif de Cap 9 vers les stores, puis reprendre ou étendre les déploiements progressifs OTA Capgo sur le canal correspondant.
Capacitor 9 consiste surtout à « régler les dépréciations et s’aligner sur les toolchains Android et Apple modernes ». Faire ce travail sur Cap 8 garde votre diff de mise à niveau réduit et vos plugins compatibles avec les équipes qui publient encore des versions 8.x aujourd’hui.