Troubleshooting

Aquí hay algunos problemas comunes que podrías encontrar al usar Capgo y cómo resolverlos.

¿Necesita Ayuda Expertizada?

Stuck with a complex issue? Our expert team is here to help! Get personalized support, code reviews, and custom solutions tailored to your specific needs.

Obtenga Soporte Profesional

Fallas de carga

Si su carga de paquete falla, compruebe lo siguiente:

• Su ID de aplicación en capacitor.config.ts coincide con su aplicación en la consola de Capgo.
• Está ejecutando el comando de carga desde la raíz de su proyecto Capacitor
• Sus activos web están construidos y actualizados

Opciones de carga avanzadas

El Capgo CLI proporciona algunas banderas adicionales para ayudar con problemas de carga comunes:

• --tus: Utiliza el protocolo de carga resumible de tus para subidas más fiables de paquetes grandes o en conexiones de red pobres. Si su paquete es mayor de 10MB o está en una conexión inestable, considere utilizar --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json y --node-modules: Indica a Capgo dónde encontrar su carpeta raíz package.json y node_modules Si su aplicación utiliza una estructura no estándar como un monorepo o un espacio de trabajo npm, pase la ruta a la raíz. package.json y el --node_modules ruta:

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo needs this information to correctly bundle your app’s dependencies.

Puedes combinar estas banderas con otras opciones como --channel según sea necesario. Consulta los docs Capgo CLI for full details on the available upload options.

Si sigues teniendo problemas con las cargas, ponte en contacto con Capgo soporte para obtener asistencia adicional.

Depuración de Actualizaciones

Si está experimentando problemas con las actualizaciones en vivo, el comando de depuración Capgo es una herramienta útil para la depuración. Para utilizarlo:

1. Ejecuta el siguiente comando en el directorio de tu proyecto:

   npx @capgo/cli@latest app debug

2. Lanza tu aplicación en un dispositivo o emulador y realiza la acción que debería desencadenar una actualización (por ejemplo, volver a abrir la aplicación después de subir un nuevo paquete).

3. Observa la salida del comando de depuración. Mostrará información sobre el proceso de actualización, incluyendo:

   • When the app checks for an update
   • Si se encuentra una actualización y qué versión es
   • Progreso de descarga e instalación para la actualización
   • Errores que ocurren durante el proceso de actualización

4. Use the debug logs to identify where the issue is occurring. For example:

   • Si no se encuentra actualización, compruebe que su paquete se subió correctamente y que la aplicación está configurada para utilizar el canal correcto.
   • Si el update se descarga pero no se instala, asegúrese de que ha llamado CapacitorUpdater.notifyAppReady() and that the app was fully closed and reopened.
   • Si ve un mensaje de error, busque ese error específico en los Capgo docs o póngase en contacto con el soporte para obtener ayuda.

El comando de depuración es especialmente útil para identificar problemas con el proceso de descarga y instalación de actualizaciones. Si los registros muestran que la versión de actualización esperada se encontró pero no se aplicó finalmente, centre su investigación en los pasos después de la descarga.

Depuración con Registros Nativos

Además del comando de depuración de Capgo, los registros nativos en Android, iOS y Electron pueden proporcionar información de depuración valiosa, especialmente para problemas en el lado nativo del proceso de actualización.

Registros de Android

Para acceder a los registros de Android:

1. Conecta tu dispositivo o inicia tu emulador
2. Abre Android Studio y selecciona "Ver > Ventanas de herramienta > Logcat"
3. In the Logcat window, filter the logs to just your app’s process by selecting it from the dropdown at the top
4. Busca cualquier línea que incluya Capgo para encontrar los registros de SDK

En su lugar, puedes utilizar el adb logcat para filtrar los registros. Capgo Filtrar los registros.

El Capgo SDK registrará eventos clave durante el proceso de actualización, como:

• When an update check is initiated
• Si se encuentra una actualización y qué versión es
• Busca cualquier línea que incluya __CAPGO_KEEP_0__
• When the installation of the update is triggered
• Errores que ocurran durante los pasos de actualización nativa

Common issues specific to Android that you might see in the logs include:

• Problems with network connectivity that prevent the update download
• Errors with file permissions when saving or reading the update bundle
• No space available on the device for the update bundle
• Falla al reiniciar la aplicación después de instalarse la actualización

Registros de iOS

Para acceder a los registros de iOS:

1. Conecta tu dispositivo o inicia tu simulador
2. Abre Xcode y ve a “Ventana > Dispositivos y simuladores”
3. Seleccione su dispositivo y haga clic en "Abrir Consola".
4. En la salida de la consola, busque cualquier línea que incluya Capgo para encontrar los registros de SDK.

También puede utilizar el log stream comando en la terminal y grep para Capgo para filtrar los registros.

De manera similar a Android, el Capgo SDK registrará eventos clave del lado iOS:

• Verificación de actualizaciones
• El inicio, progreso y completación del descarga
• El disparo y resultado de la instalación
• Errores durante el proceso de actualización nativa

iOS-specific issues you might identify in the logs include:

• Problemas con certificado SSL al descargar la actualización
• App transport security blocking the update download
• Insufficient storage space for the update bundle
• Falló la extracción o aplicación correcta del paquete de actualización

Registros de Electron

For Electron apps, check both the main process and renderer process output:

1. Ejecuta la aplicación de Electron desde tu terminal utilizando tu comando de lanzamiento normal (por ejemplo bun run electron:dev o bun run electron:servey observe el terminal para la salida de inicio, verificación de actualizaciones y errores de red.
2. Abra la consola del navegador (Ver → Herramientas de Desarrollador) e inspeccione los registros de la consola y las solicitudes de red fallidas mientras reproduce el flujo de actualización.
3. For packaged apps, check OS log tools for crashes or startup failures:
   • macOS: abrir Console.app y filtrar por el nombre de tu aplicación
   • Windows: abrir Registro de Eventos → Registro de Windows → Aplicación
   • Linuxutilice su visor de registros de escritorio journalctl para el proceso de tu aplicación

When debugging updates, compare messages from both main-process and renderer-process logs to separate Electron bootstrap issues from Capgo update lifecycle issues.

En todas las plataformas, los registros nativos proporcionan una vista de nivel inferior en el proceso de actualización, con más detalles sobre la implementación nativa. Son especialmente útiles para identificar problemas que ocurren fuera de la capa JavaScript Capgo.

Cuando se está resolviendo un problema live update complicado, es una buena idea capturar tanto los registros de depuración Capgo como los registros nativos para obtener una imagen completa de qué está sucediendo. Los dos registros juntos le darán la mejor oportunidad de identificar y resolver el problema.

Actualizaciones no se aplican

Si ha subido un paquete pero no ve los cambios en su dispositivo:

• Verifique que ha llamado a CapacitorUpdater.notifyAppReady() en su aplicación code como se muestra en el quickstart
• Verifique que su dispositivo está conectado a Internet y los registros de depuración Capgo muestran que la actualización se descargó
• Try fully closing and reopening the app, as updates are only applied on a fresh launch
• Busque cualquier error en los registros nativos que pueda indicar un problema al aplicar la actualización

Consulte el desplegando actualizaciones en vivo Guía para obtener más detalles sobre el proceso de actualización. Si aún tienes problemas, utiliza npx @capgo/cli@latest app debug comando y registros nativos para obtener más visibilidad sobre lo que está sucediendo.

Códigos de falla de actualización comunes

Si tus registros muestran errores de backend como disable_auto_update_to_major, semver_erroro cannot_update_via_private_channelutiliza la guía dedicada:

• Problemas de actualización comunes

Explica qué significa cada code común, por qué sucede y cómo solucionarlo.

SDK de instalación

Si está teniendo problemas para instalar el Capgo SDK, asegúrese de:

• Su aplicación utiliza una versión compatible de Capacitor (4.0 o posterior)
• Ha seguido los pasos del quickstart pasos en orden, incluido el sincronización de la aplicación después de instalar el SDK

Integración CI/CD

Para problemas con la activación de subidas de Capgo desde su pipeline de CI/CD:

• Verifique que su token de autenticación de Capgo esté configurado correctamente
• Asegúrese de ejecutar el comando de carga después de que se hayan construido sus activos web.
• Verifique que el comando de subida esté utilizando el nombre de canal correcto para su entorno de destino

Consulte la integración CI/CD docs for more troubleshooting tips. You can also use the npx @capgo/cli@latest app debug command to confirm if your CI/CD-triggered updates are being received by the app.

Título de la sección “Continuar desde Depuración”

Si estás utilizando Troubleshooting @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-almacenamiento-de-datos-sqlite @capgo/capacitor-data-storage-sqlite para el detalle de implementación en @capgo/capacitor-almacenamiento-de-datos-sqlite, Usando @capgo/capacitor-almacenamiento-de-datos-sqlite para la capacidad nativa en Uso de @capgo/capacitor-almacenamiento-sqlite. archivo de capgo/capacitor para el detalle de implementación en archivo de capgo/capacitor Usando archivo de capgo/capacitor para la capacidad nativa en Usando archivo de capgo/capacitor, y subidor de capgo/capacitor para el detalle de implementación en subidor de capgo/capacitor.