Cómo actualizar su aplicación Capacitor a Capacitor 8

Para actualizar una aplicación Capacitor a Capacitor 8, instale Node.js 22+, Xcode 26+ y Android Studio Otter, actualice @capacitor/cli al último 8.x, ejecute bunx cap migrate, luego corrija lo que informe el migrador. Los principales cambios de compatibilidad son iOS 15 como objetivo de despliegue mínimo, Android SDK 36 con minSdk 24, AGP 8.13 con Gradle 8.14.3 y la eliminación de adjustMarginsForEdgeToEdge en lugar de la nueva plugin de Barras del Sistema.

Esta guía recorre el camino automatizado, cada paso manual detrás de él, y los errores que la gente encuentra con más frecuencia después de la actualización. Si mantienes una plugin en lugar de una aplicación, lee Cómo actualizar tu plugin de Capacitor a Capacitor 8 en su lugar.

Requisitos de Capacitor 8 a la vista

Verifique su cadena de herramientas antes de tocar el proyecto. La mayoría de las actualizaciones fallidas son un JDK antiguo, un Xcode antiguo o un Node antiguo en CI, no el code.

Xcode 26 no es solo un Capacitor requisito. Desde el 28 de abril de 2026, App Store Connect rechaza subidas construidas con una versión anterior de Xcode, por lo que lo necesitas de cualquier manera. Consulta Requisito de Xcode 26 de Apple para Capacitor apps para obtener más detalles.

Antes de empezar

1. Comita todo, o crea una rama. El migrador edita archivos nativos en lugar.
2. Asegúrese de que la aplicación se compile en Capacitor 7 hoy. Actualizar un proyecto roto solo añade ruido.
3. Si está en Capacitor 6 o anterior, haga el anterior mayor primero. Cada mayor tiene su propia lógica de migración en el CLI.
4. Liste sus plugins con bunx cap ls y verifica que cada uno tenga una versión que soporte Capacitor 8. Mira peerDependencies de la última versión:

bun pm view @capgo/capacitor-updater peerDependencies

A un plugin con @capacitor/core: ^7.0.0 sus pares instalarán con advertencias y pueden fallar al compilar. Los plugins Capgo siguen la versión mayor Capacitor en su propio número de versión, por lo que @capgo/* 8.x lanzamientos apuntan a Capacitor 8.

5. Actualice herramientas locales y de CI: Node 22, Xcode 26, JDK 21, Android Studio Otter. En GitHub Actions, fije una imagen de macOS que envía Xcode 26 y utilice actions/setup-java con java-version: '21'.

Opción 1: actualice con cap migrate

El CLI envía un comando de migración que maneja la mayoría del trabajo. Instale la última CLI, luego ejecute

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

El migrador pregunta si debe instalar los nuevos paquetes de Capacitor y le permite elegir npm, Yarn, pnpm o Bun. Elija Bun si su proyecto tiene un bun.lockPuede saltar la pregunta con bunx cap migrate --noprompt.

¿Qué cambia para ti:

• Actualiza @capacitor/core, @capacitor/ios, @capacitor/android y oficial @capacitor/* plugins a 8.x.
• Sets IPHONEOS_DEPLOYMENT_TARGET = 15.0 en el proyecto Xcode y platform :ios, '15.0' en el archivo Podfile.
• Actualizaciones variables.gradlela clase AGP, el classpath de Gradle y el wrapper de Gradle kotlin_version.
• Adds density Agrega android:configChanges para 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.

Cuando termine:

bun run build
bunx cap sync

Luego abre cada plataforma y compila una vez desde el IDE para ver errores nativos en su totalidad.

Opción 2: actualizar manualmente

Si sus proyectos nativos están muy personalizados, o el migrador omitió pasos, aplique los cambios a mano. Estos coinciden con Actualice los paquetes Capacitor.

Actualice los paquetes npm.

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

Actualice luego cada plugin oficial, por ejemplo:

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

En Xcode, seleccione el proyecto, abra

Configuración de compilación Configuración de compilación, find iOS Deployment Target Despliegue Deployment y establezca en 15.0. Repita para cada destino de aplicación, incluidas las extensiones.

Si la aplicación sigue utilizando CocoaPods, actualice ios/App/Podfile:

platform :ios, '15.0'

Entonces ejecute bunx cap sync ios, que ejecuta pod install para usted.

Si la aplicación utiliza SPM, el CLI se regenera ios/App/CapApp-SPM/Package.swift con cada sincronización con la versión de plataforma correcta y una versión exacta capacitor-swift-pm no edite ese archivo a mano. @capacitor/iosiOS: elimine las notificaciones de controlador de vista personalizado

iOS: eliminar notificaciones de controlador de vista personalizado

Capacitor ahora emite CAPBridgeViewController notificaciones viewDidAppear y viewWillTransition si agregaste una extensión o subclase a post .capacitorViewDidAppear o .capacitorViewWillTransitionborre, eliminará, o los listeners dispararán dos veces.

Android: actualice Android Studio y AGP

Instale Android Studio Otter o una versión más reciente, abra la android carpeta y ejecute Herramientas > Asistente de actualización de AGP. Elija 8.13.0 y ejecute los pasos seleccionados. O edite android/build.gradle directamente:

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

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

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

Android: actualice 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'
}

Mantenga cualquier variable adicional que sus plugins lean (por ejemplo) firebaseMessagingVersion. Actualizaciones oficiales de plugins para Capacitor 8 incluyen firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' y androidxExifInterfaceVersion = '1.4.1'.

Android: cambie a = la asignación en archivos Gradle

Gradle ha deprecado la sintaxis de asignación de espacio. Solo advierte hoy, pero romperá en una futura versión de Gradle, así que corrija ahora en 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:!*~'
         }
     }
}

llamadas de método como google() o mavenCentral() Quédense tal como están.

Android: cambie a configChanges

la asignación en archivos Gradle kotlin_version = '2.2.20'Kotlin 2.x convierte la antigua kotlinOptions {} bloque en un error, así que muevete jvmTarget a kotlin { compilerOptions { ... } }.

Entonces agrega density Para evitar que la WebView se vuelva a crear cuando cambian la densidad de pantalla (dispositivos plegables, ajustes de tamaño de ventana, ajustes de tamaño de pantalla):

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

Android: el layout de puente se renombró

bridge_layout_main.xml ya no existe. Si tu MainActivity o un fragmento personalizado referenciado R.layout.bridge_layout_main, usa R.layout.capacitor_bridge_layout_main.

Borde a bordo y el nuevo plugin de Barras de Sistema

Esto es el cambio más probable que se muestre visualmente. Capacitor 8 eliminado android.adjustMarginsForEdgeToEdge y agregó un plugin de barras del sistema central. No lo instalas, viene con @capacitor/core.

Android 15 fuerza el borde a borde para aplicaciones que targetean SDK 35, y Android 16 elimina la opción de exención para aplicaciones que targetean SDK 36. Capacitor 8 targetea 36, por lo que tu contenido web ahora dibuja detrás de las barras de estado y navegación a menos que manejes los recuadros.

The plugin config se encuentra bajo 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;

Con css o nativenuevos Android WebViews (Chromium 140+) que respetan viewport-fit=cover y reportar en tiempo real env(safe-area-inset-*) valores. En navegadores web más antiguos, Capacitor amplía el navegador web y establece los valores de entorno a 0pxAsí, establezca la etiqueta meta y utilice las 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);
}

At runtime you can change bar style or visibility:

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

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

Aplicaciones de Ionic Framework ya utilizan las variables de área segura, por lo que normalmente solo necesitan la etiqueta meta. Otros cambios de comportamiento para verificar describe la opción 7 del Capacitor, que ya no existe en la versión 8.

Otros cambios de comportamiento para verificar

• appendUserAgent On iOS: Capacitor 7 agregó dos espacios antes de tu cadena, Capacitor 8 agrega uno. Si tu servidor parsea el agente de usuario estrictamente, agrega un espacio al principio ios.appendUserAgent (no la opción raíz, que también afecta a Android).
• Pantalla de Orientación y Lector de Códigos de BarrasEn dispositivos Android 16+ con pantallas grandes, se ignoran los bloqueos de orientación. Existe una opción temporal para excluirse de esta función. android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY propiedad de manifest, pero Android 17 la elimina.
• Geolocation: timeout Ahora se aplica a todas las solicitudes en Android e iOS. Si ves nuevos tiempos de espera, aumenta el valor. watchPosition Barra de Estado interval option.
• pluginEl plugin ya no envía su propio CAPBridgeViewController archivos de notificación, ya que el núcleo ahora emite esos eventos.
• Nuevas plataformas de iOS por defecto utilizan SPM: bunx cap add ios ahora crea un proyecto de SPM. Utilice --packagemanager CocoaPods si necesita el antiguo modelo. Consulte cómo utilizar CocoaPods con Capacitor 8.

Verifique la actualización

Ejecuta esta lista en ambas plataformas antes de enviar:

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

• cap doctor muestra versiones 8.x coincidentes para el núcleo, CLI, iOS y Android.
• App launches, splash screen hides, deep links open the right screen.
• Barra de estado y barra de navegación se ven bien en un dispositivo Android 15/16 y en un iPhone con notched.
• Notificaciones de empuje, cámara, acceso a archivos y cualquier plugin con permisos nativos todavía funcionan.
• Un paquete de liberación (Archivo en Xcode, ./gradlew bundleRelease) tiene éxito, no solo depuración.

Si no deseas mantener Xcode 26 y JDK 21 en cada máquina, Capgo Construcción ejecuta las compilaciones de iOS y Android en la nube con herramientas de compilación actuales.

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 utilizas 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 comprobación de compatibilidad comprobación de compatibilidad

bunx @capgo/cli@latest bundle compatibility

Compara las versiones de los plugins nativos en tu paquete con las que están ejecutándose en el canal y marca las incompatibilidades antes de que los usuarios reciban una actualización rota.

Resolviendo errores comunes de actualización Capacitor 8

The engine "node" is incompatible o el CLI se niega a ejecutarse. Estás en Node 20 o anterior. Instala Node 22 LTS y actualiza también la imagen de tu CI.

error: invalid source release: 21 en Android. Gradle está ejecutándose con JDK 17. Puntual a su JDK 21 incorporado en Android Studio (Configuración > Construcción, ejecución y depuración > Herramientas de construcción > Gradle > JDK de Gradle) y establece JAVA_HOME to a JDK 21 for command-line and CI builds.

Minimum supported Gradle version is 8.13. Actualizaste AGP pero no el wrapper. Establece el wrapper a 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion todavía es 35 en algún lugar. Verifica variables.gradle y cualquier plugin que lo haya codificado.

Using 'kotlinOptions' ... is an error o errores de DSL de Kotlin similares. Un plugin o tu módulo de aplicación todavía utiliza kotlinOptionsActualice el plugin, o parchee hasta que salga una versión (consulte cómo parchear un Capacitor plugin).

Xcode: No such module 'Capacitor' después de la actualización. Para CocoaPods, abra App.xcworkspace, no App.xcodeprojy volver a ejecutar bunx cap sync ios. Para SPM, utilice Archivo > Paquetes > Reiniciar cachés de paquetes.

"X" plugin is not implemented on ios/android. El plugin no se sincronizó, o no tiene una versión Capacitor 8 / compatible con SPM. Ejecute bunx cap sync y lea las advertencias.

Para una lista más larga, consulte el Capacitor Guía de depuración de iOS y la Guía de depuración de Android. Se cubren las versiones de núcleo y plugin desalineadas en solucionar errores de versión Capacitor desalineada.

Let an AI agent do the boring parts

Si utiliza Claude Code, Cursor o un agente similar, el Capgo Habilidades incluyen capacitor-app-upgrade-v7-to-v8 y capacitor-app-upgrades para saltos de versión multi-mayor. Instalelas con bunx skills add Cap-go/capgo-skills y pida al agente que actualice la aplicación. Ejecuta el migrador, luego verifica los pasos que el CLI suele omitir, como la sintaxis de Gradle, las opciones de Kotlin y las imágenes de CI.

¿Qué viene a continuación

Capacitor 9 ya está en versión de pruebas. Una vez que estés establecido en 8, lee Preparándose para Capacitor 9 El próximo upgrade es más pequeño.