Comment mettre à niveau votre application Capacitor vers Capacitor 8

Pour mettre à niveau une application Capacitor vers Capacitor 8, installez Node.js 22+, Xcode 26+ et Android Studio Otter, mettez à jour @capacitor/cli exécutez la dernière version 8.x bunx cap migrateFixez ensuite les problèmes signalés par le migrateur. Les principaux changements de rupture sont iOS 15 comme cible de déploiement minimale, Android SDK 36 avec minSdk 24, AGP 8.13 avec Gradle 8.14.3 et la suppression de adjustMarginsForEdgeToEdge en faveur du nouveau plugin de barres système.

Cet article vous guide à travers la voie automatique, chaque étape manuelle qui la suit, et les erreurs auxquelles les gens tombent le plus souvent après la mise à niveau. Si vous gérez un plugin plutôt qu'une application, lisez Comment mettre à niveau votre plugin Capacitor vers Capacitor 8 instead.

Capacitor 8 en un coup d'œil

Vérifiez votre chaîne d'outils avant de toucher au projet. La plupart des mises à niveau échouées sont un JDK ancien, un Xcode ancien ou un Node ancien dans CI, pas le code.

Xcode 26 n'est pas seulement un Capacitor exigence. Depuis le 28 avril 2026, App Store Connect rejette les téléchargements construits avec un Xcode plus ancien, donc vous en avez besoin de toute façon. Voir Exigence d'Apple Xcode 26 pour les Capacitor applications pour plus de détails.

Avant de commencer

1. Enregistrez tout, ou créez une branche. Le migrateur modifie les fichiers natifs en place.
2. Assurez-vous que l'application se construit sur Capacitor 7 aujourd'hui. Mettre à niveau un projet cassé ne fait que créer du bruit.
3. Si vous êtes sur Capacitor 6 ou plus ancien, effectuez la mise à niveau majeure précédente en premier. Chaque majeure a sa propre logique de migration dans le CLI.
4. Listez vos plugins avec bunx cap ls et vérifiez que chaque un a une mise à jour supportant Capacitor 8. Regardez les peerDependencies de la dernière version :

bun pm view @capgo/capacitor-updater peerDependencies

Un plugin avec @capacitor/core: ^7.0.0 comme pair installera avec des avertissements et peut échouer à compiler. Les plugins Capgo suivent la Capacitor majeure dans leur propre numéro de version, donc @capgo/* 8.x sorties ciblent Capacitor 8.

5. Mettez à jour vos outils locaux et CI : Node 22, Xcode 26, JDK 21, Android Studio Otter. Dans GitHub Actions, fixez une image macOS qui embarque Xcode 26 et utilise actions/setup-java avec java-version: '21'.

Option 1 : mettre à jour avec cap migrate

Le CLI embarque une commande de migration qui gère la plupart du travail. Installez la dernière CLI, puis exécutez-la :

bun add -D @capacitor/cli@latest
bunx cap migrate

Le migrateur demande si elle doit installer les nouveaux paquets Capacitor et vous permet de choisir entre npm, Yarn, pnpm ou Bun. Choisissez Bun si votre projet a un bun.lockVous pouvez ignorer la question avec bunx cap migrate --noprompt.

Ce qu'il change pour vous :

• Bumps @capacitor/core, @capacitor/ios, @capacitor/android et officiel @capacitor/* Configure les
• Sets IPHONEOS_DEPLOYMENT_TARGET = 15.0 dans le fichier Podfile. platform :ios, '15.0' dans le fichier Podfile.
• Mises à jour variables.gradleMises à jour, la classe AGP, le wrapper Gradle et kotlin_version.
• Ajoute density à android:configChanges in AndroidManifest.xml.

Read the full output. When a step cannot be applied, for example because a file was customized, the CLI prints an error with the file name and continues. Those lines are your manual to-do list.

Lorsqu'il est terminé :

bun run build
bunx cap sync

Ouvrez ensuite chaque plateforme et construisez-l’une fois depuis l'IDE afin de voir les erreurs natives en détail.

Option 2 : mettre à jour manuellement

Si vos projets natifs sont fortement personnalisés, ou que le migrateur a omis des étapes, appliquez les modifications à la main. Ces modifications correspondent à Mettez à jour les packages Capacitor.

Mettez à jour les packages npm.

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

Mise à jour ensuite chaque plugin officiel, par exemple :

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

iOS : augmentez la cible de déploiement à 15.0

Dans Xcode, sélectionnez le projet, ouvrez Réglages de compilation, recherchez Cible de déploiement iOS sous Déploiement et définissez-la sur 15.0. Répétez pour chaque cible d'application, y compris les extensions.

Si l'application utilise toujours CocoaPods, mettez à jour ios/App/Podfile:

platform :ios, '15.0'

Exécutez ensuite bunx cap sync ios, qui exécute pod install pour vous.

Si l'application utilise SPM, le CLI se régénère ios/App/CapApp-SPM/Package.swift sur chaque synchronisation avec la bonne version de la plateforme et une version exacte capacitor-swift-pm N'éditez pas ce fichier à la main. @capacitor/iosiOS : supprimez les notifications de contrôleur de vue personnalisées

__CAPGO_KEEP_0__ 8 émet désormais des notifications pour

Capacitor 8 émet maintenant CAPBridgeViewController notifications pour viewDidAppear ou viewWillTransition ou supprimez-le, ou les écouteurs se déclencheront deux fois. .capacitorViewDidAppear or .capacitorViewWillTransitionet supprimez-le, ou les écouteurs se déclencheront deux fois.

Android : mettre à jour Android Studio et AGP

Installez Android Studio Otter ou une version plus récente, ouvrez le android répertoire et exécutez Outils > Assistant de mise à jour AGP. Choisissez 8.13.0 et exécutez les étapes sélectionnées. Ou éditez android/build.gradle directement :

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

Et android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

Android : mettre à jour variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

Conservez les variables supplémentaires que vos plugins lisent (par exemple firebaseMessagingVersionOfficial plugin bumps pour Capacitor 8 incluent firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' et androidxExifInterfaceVersion = '1.4.1'.

Android : basculer vers = l'assignation dans les fichiers Gradle

Gradle deprecated the space-assignment syntax. It only warns today, but it will break in a future Gradle release, so fix it now in android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

appels de méthode comme google() ou mavenCentral() reste tels quels.

restent comme elles sont. configChanges

If your app module uses Kotlin, set kotlin_version = '2.2.20'Si votre module d'application utilise Kotlin, définissez kotlinOptions {} . Kotlin 2.x transforme l'ancienne jvmTarget into kotlin { compilerOptions { ... } }.

en density Pour éviter la re création de la vue WebView lors des changements de densité d'écran (pliants, redimensionnement de la fenêtre, réglages de la taille de l'écran).

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android : le layout de pont a été renommé

bridge_layout_main.xml n'existe plus. Si votre MainActivity ou un fragment personnalisé référencé R.layout.bridge_layout_mainutilisez R.layout.capacitor_bridge_layout_main.

et le nouveau plugin de barres système

C'est la modification la plus susceptible de se manifester visuellement. Capacitor 8 supprimé android.adjustMarginsForEdgeToEdge et ajouté un plugin de barres système central. Vous n'installez pas, il est livré avec @capacitor/core.

Android 15 impose un écran plein écran pour les applications ciblées par SDK 35, et Android 16 supprime l'option de dérogation pour les applications ciblées par SDK 36. Capacitor 8 cible 36, donc votre contenu web se dessine maintenant derrière les barres de statut et de navigation sauf si vous gérez les insets.

Le plugin de configuration se trouve sous plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

ou css context native, les nouvelles versions Web d'Android (Chromium 140+) respectent viewport-fit=cover et signaler des valeurs réelles. env(safe-area-inset-*) valeur. Sur les anciens WebViews, Capacitor ajoute un padding au WebView et définit les valeurs d'environnement à 0px. Définissez ensuite la balise meta et utilisez les variables :

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

À l'exécution, vous pouvez modifier le style ou la visibilité de la barre :

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Ionic Framework applications utilisent déjà les variables de zone de sécurité, ils n'ont donc généralement besoin que de la balise meta. sans plugins de bord décrit l'option Capacitor 7, qui n'existe plus en 8.

Autres modifications de comportement à vérifier

• appendUserAgent sur iOS: Capacitor 7 ajoutait deux espaces avant votre chaîne, Capacitor 8 en ajoute un. Si votre serveur traite l'agent utilisateur de manière stricte, ajoutez un espace avant ios.appendUserAgent (pas l'option de racine, qui affecte également Android).
• Orientation de l'écran et Lecteur de code-barres: sur Android 16+, les écrans larges ignorent les verrous d'orientation. Un opt-out temporaire existe par le android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY propriété de manifeste, mais Android 17 la supprime.
• La géolocalisation: timeout Maintenant s'applique à toutes les requêtes sur Android et iOS. Si vous voyez de nouveaux temps d'attente, augmentez la valeur. watchPosition une option supplémentaire interval option.
• Barre de statut: le plugin n'expédie plus son propre CAPBridgeViewController les fichiers de notification, puisque le noyau émet désormais ces événements.
• Nouveaux plateformes iOS par défaut utilisent SPM: bunx cap add ios Maintenant crée un projet SPM. Utilisez --packagemanager CocoaPods Si vous avez besoin de l'ancien modèle. Consultez How utiliser CocoaPods avec Capacitor 8.

Vérifiez l'upgrade

Exécutez cette liste sur les deux plateformes avant de livrer :

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor affiche des versions 8.x correspondantes pour le noyau, CLI, iOS et Android.
• L'application démarre, la page d'accueil se cache, les liens profonds ouvrent l'écran approprié.
• Barre de statut et barre de navigation affichent correctement sur un appareil Android 15/16 et sur un iPhone à notches.
• Les notifications push, la caméra, l'accès aux fichiers et tout plugin avec des permissions natives fonctionnent toujours.
• Une archive de production (Archive dans Xcode, ./gradlew bundleRelease) réussit, non seulement en mode debug.

Si vous ne souhaitez pas maintenir Xcode 26 et JDK 21 sur chaque machine, Capgo Construction exécute les builds iOS et Android dans le cloud avec les outils actuels.

Ship the upgrade safely with live updates

Une mise à niveau majeure de Capacitor change les code natifs, elle doit donc passer par l'App Store et Google Play. Les bundles web créés après la mise à niveau peuvent appeler les API des plugins qui ne sont pas disponibles dans les anciens binaires.

Si vous utilisez les mises à jour en temps réel de Capgogardez les utilisateurs Capacitor 7 et Capacitor 8 séparés jusqu'à ce que l'adoption rattrape le retard : mettez à jour votre version native, envoyez de nouvelles archives dans un canal utilisé par le nouveau binaire, et exécutez le vérificateur de compatibilité avant de les envoyer :

bunx @capgo/cli@latest bundle compatibility

Il compare les versions des plugins natifs dans votre bundle avec celles en cours sur le canal et signale les incohérences avant que les utilisateurs ne reçoivent une mise à jour défectueuse.

Résoudre les erreurs courantes de mise à niveau vers Capacitor 8

The engine "node" is incompatible ou que CLI refuse de s'exécuter. Vous utilisez Node 20 ou une version plus ancienne. Installez Node 22 LTS et mettez à jour également votre image CI.

error: invalid source release: 21 sur Android. Gradle fonctionne avec JDK 17. Pointez Android Studio vers son JDK 21 intégré (Paramètres > Outils de construction, exécution et déploiement > Outils de construction > Gradle > JDK de Gradle) et définissez JAVA_HOME à une JDK 21 pour les builds en ligne de commande et CI.

Minimum supported Gradle version is 8.13. Vous avez mis à jour AGP mais pas le wrapper. Définissez le wrapper sur 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion est toujours 35 quelque part. Vérifiez variables.gradle et tout plugin qui le fixe dur.

Using 'kotlinOptions' ... is an error ou des erreurs similaires de DSL Kotlin. Un plugin ou votre module d'application utilise encore kotlinOptions. Mettez à jour le plugin, ou le patchez jusqu'à la prochaine mise à jour (voir comment patcher un Capacitor plugin).

Xcode : No such module 'Capacitor' après l'upgrade. Pour CocoaPods, ouvrez App.xcworkspace, pas App.xcodeproj, et relancez bunx cap sync iosPour SPM, utilisez Fichier > Packages > Réinitialiser les caches de packages.

"X" plugin is not implemented on ios/android. Le plugin n'a pas été synchronisé, ou il n'a pas de Capacitor 8 / SPM compatible. bunx cap sync lisez les avertissements.

et lisez les avertissements. Capacitor iOS troubleshooting guide et le Guide de dépannage AndroidMauvaises versions de la plateforme et des plugins sont abordées dans fix Capacitor erreurs de version incohérentes.

Let an AI agent do the boring parts

Si vous utilisez Claude Code, Cursor ou un agent similaire, l'ouverture Capgo Compétences inclure capacitor-app-upgrade-v7-to-v8 et capacitor-app-upgrades pour les sauts majeurs multi-majeurs. Installez-les avec bunx skills add Cap-go/capgo-skills and ask the agent to upgrade the app. It runs the migrator, then checks the steps the CLI usually misses, such as Gradle syntax, Kotlin options and CI images.

Qu'est-ce qui suit

Capacitor 9 est déjà en préversion. Une fois que vous êtes stable sur 8, lisez Préparez-vous à l'Capacitor 9 La prochaine mise à jour est plus petite.