Comment mettre à niveau votre application Capacitor vers Capacitor 8

Pour mettre à niveau une application Capacitor à Capacitor 8, installez Node.js 22+, Xcode 26+ et Android Studio Otter, mettez à jour @capacitor/cli à la dernière version 8.x, exécutez bunx cap migratepuis corrigez tout ce que le migrateur signale. Les principaux changements de rupture sont iOS 15 comme cible de déploiement minimum, 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.

Ce guide vous guide à travers le chemin automatique, chaque étape manuelle qui le 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 au lieu de cela.

Exigences de Capacitor 8 en un coup d'œil

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

Le 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, vous en avez donc besoin de toute façon. Consultez Exigences de Xcode 26 pour les Capacitor applications pour plus de détails.

Avant de commencer

1. Commitez tout, ou créez une branche. Le migrateur modifie les fichiers natifs sur 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. If you are on Capacitor 6 or older, do the previous major first. Each major has its own migration logic in the CLI.
4. Listez vos plugins avec bunx cap ls et vérifiez que chaque une d'elles a une version supportant Capacitor 8. Regardez les peerDependencies de la dernière version :

bun pm view @capgo/capacitor-updater peerDependencies

Avec un plugin avec @capacitor/core: ^7.0.0 Comme son pair, il sera installé avec des avertissements et peut ne pas compiler. Les Capgo plugins suivent la Capacitor majeure dans leur propre numéro de version, donc @capgo/* 8.x sorties ciblent Capacitor 8.

5. Update local and CI toolchains: Node 22, Xcode 26, JDK 21, Android Studio Otter. In GitHub Actions, pin a macOS image that ships Xcode 26 and use actions/setup-java with java-version: '21'.

Option 1 : mettre à jour avec cap migrate

Le CLI fournit un commandement de migration qui gère la plupart du travail. Installez la dernière CLI, puis exécutez-le.

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

The migrator asks whether it should install the new Capacitor packages and lets you pick npm, Yarn, pnpm or Bun. Pick Bun if your project has a bun.lockVous pouvez passer outre le prompt avec bunx cap migrate --noprompt.

Vous pouvez ignorer la prompt avec

• Bumps @capacitor/core, @capacitor/ios, @capacitor/android Augmente les versions de @capacitor/* plugins à 8.x.
• Mises à jour IPHONEOS_DEPLOYMENT_TARGET = 15.0 dans le projet Xcode et platform :ios, '15.0' dans le fichier Podfile.
• Mises à jour variables.gradle, la classe AGP de chemin d'accès, le wrapper Gradle et kotlin_version.
• Adds density Ajoute android:configChanges à 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 exécutez une compilation depuis l'IDE pour afficher 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 changements manuellement. Ces modifications correspondent à guide de mise à jour officiel Capacitor 8.

Mettez à jour les packages npm

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

Mettez ensuite à jour 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 Paramètres de compilation, recherchez Cible de déploiement iOS sous Déploiement et définissez-le sur 15.0. Répétez l'opération 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 du plateforme et une version exacte capacitor-swift-pm de . Ne modifiez pas ce fichier manuellement. @capacitor/iosiOS : supprimez les notifications de contrôleur de vue personnalisées

__CAPGO_KEEP_0__ 8 émet maintenant

Capacitor 8 émet maintenant CAPBridgeViewController les notifications pour viewDidAppear And viewWillTransition si vous avez ajouté une extension ou une sous-classe à post. .capacitorViewDidAppear or .capacitorViewWillTransitionSupprimez-le, sinon les listeners se déclencheront deux fois.

Android : mettez à jour Android Studio et AGP

ou mettre à jour Android Studio et AGP android dossier et exécutez Outils > Assistant de mise à niveau AGPChoisissez 8.13.0 et exécutez les étapes sélectionnées. Ou éditez android/build.gradle directly:

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

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

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

Android : mise à 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 toute variable supplémentaire que vos plugins lisent (par exemple firebaseMessagingVersion. Les mises à jour officielles de Capacitor 8 incluent firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' et androidxExifInterfaceVersion = '1.4.1'.

Android : passez à = l'attribution 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:!*~'
         }
     }
}

Les appels de méthode comme google() ou mavenCentral() reste comme elles sont.

Android : Kotlin et configChanges

restent comme elles sont. kotlin_version = '2.2.20'Android : Kotlin et kotlinOptions {} ne tombe pas en erreur, déplacez donc jvmTarget vers kotlin { compilerOptions { ... } }.

Ensuite ajoutez 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.

Edge-to-edge 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 un plugin de barres système de base ajouté. Vous n'installez pas cela, il est livré avec @capacitor/core.

Android 15 impose l'edge-to-edge pour les applications ciblées vers SDK 35, et Android 16 supprime l'option de dérogation pour les applications ciblées vers 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.

La configuration du plugin 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;

Avec css ou native, les nouvelles versions WebViews Android (Chromium 140+) respectent viewport-fit=cover et signaler des problèmes réels env(safe-area-inset-*) values. Sur les anciens WebViews, Capacitor ajoute un padding au WebView et définit les valeurs d'environnement à 0px. Fixezz le tag 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 ont donc généralement besoin que de la balise meta. edge-to-edge without plugins décrit l'option Capacitor 7, qui n'existe plus dans la version 8.

Autres modifications de comportement à vérifier

• appendUserAgent On iOS: Capacitor 7 ajoute 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 racine, qui affecte également Android).
• Écran d'orientation et Lecteur de code-barres: sur Android 16+, les écrans larges ignorent les verrous d'orientation. Un opt-out temporaire existe via le android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY propriété de manifest, mais Android 17 la supprime.
• Geolocation: timeout Maintenant s'applique à tous les requêtes sur Android et iOS. Si vous voyez de nouveaux temps d'attente, augmentez la valeur. watchPosition on Android gained an interval option.
• Barre de statut: le plugin n'expédie plus son propre CAPBridgeViewController les fichiers de notification, car le noyau émet désormais ces événements.
• Les nouvelles plateformes iOS par défaut utilisent SPM: bunx cap add ios crée maintenant un projet SPM. Utilisez --packagemanager CocoaPods si vous avez besoin de l'ancien modèle. Voir comment utiliser CocoaPods avec Capacitor 8.

Vérifiez l'amélioration

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 montre les versions 8.x correspondantes pour le noyau, CLI, iOS et Android.
• L'application démarre, la barre d'attente 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 version de production (Archive dans Xcode, ./gradlew bundleReleasesucceeds, pas seulement en mode débogage.

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

A Capacitor major upgrade changes native code, so it has to go through the App Store and Google Play. Web bundles built after the upgrade may call plugin APIs that older binaries don’t have.

Si vous utilisez Capgo live updates, keep Capacitor 7 users and Capacitor 8 users apart until adoption catches up: bump your native version, upload new bundles to a channel used by the new binary, and run the vérification de compatibilité contrôle de compatibilité

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 incompatibilités avant que les utilisateurs ne reçoivent une mise à jour défectueuse.

Résoudre les erreurs d'upgrade courantes du Capacitor vers la version 8

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

error: invalid source release: 21 sur Android. Gradle fonctionne avec JDK 17. Pointez Android Studio vers son JDK 21 intégré (Paramètres > Exécution, déploiement & construction > Outils de construction > Gradle > JDK 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 y fait référence.

Using 'kotlinOptions' ... is an error ou des erreurs similaires de DSL Kotlin. Un plugin ou votre module d'application utilise kotlinOptions. Mettez à jour le plugin, ou le patchez jusqu'à la sortie d'une nouvelle version (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 ios. Pour 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 release. Exécutez bunx cap sync et lisez les avertissements.

Pour une liste plus longue, voir le Capacitor guide de dépannage iOS et le guide de dépannage AndroidMauvaises versions de la couche de base et des plugins sont abordées dans fixez les erreurs de version Capacitor.

Let an AI agent do the boring parts

Si vous utilisez Claude Code, Cursor ou un agent similaire, l'ouverture de Capgo compétences incluent capacitor-app-upgrade-v7-to-v8 et capacitor-app-upgrades pour les sauts 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 vient ensuite

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