Guide de dépannage d'applications pour CapacitorJS et Electron

Un jeudi soir, votre application de shopping CapacitorJS se met à afficher des dashboards vides pour les utilisateurs sous Android 14. Les clients iOS naviguent normalement. Les utilisateurs d’Electron sur desktop n’ont rien signalé. L’ingénieur d’astreinte suppose une régression WebView, ouvre Android Studio et passe des heures à comparer le rendu entre appareils. La cause finale n’est pas un bug de rendu du tout. Une clé API de staging a atteint la production après qu’une invalidation du cache CDN n’a pas atteint les clients mobiles.

Cet incident est familier car les pannes mobiles respectent rarement les limites de votre dépôt. Un changement JavaScript récent peut être innocent, tandis qu’un déploiement, une valeur de configuration, un état de permissions, une dépendance de service ou un chemin réseau casse le parcours utilisateur. Une analyse d’incident Microsoft a révélé que 40 % des incidents de production provenaient de code ou de bugs de configuration, tandis que 60 % provenaient de l’infrastructure, du déploiement et des dépendances de services. La leçon pratique est simple : le troubleshooting d’une app doit commencer par tout le périmètre de défaillance, pas par la stack trace. (l’analyse d’incident de Microsoft)

Ce playbook suit le workflow que j’utilise après avoir déployé des releases CapacitorJS et Electron : établir exactement ce que l’utilisateur a exécuté, inspecter la télémétrie de production avant de tenter une reproduction, vérifier les causes non-code, puis déboguer la couche la plus étroite correspondant au symptôme. Les sept étapes sont : cadrage de l’incident, logs par couche, débogage web et natif, vérifications réseau et état, garde-fous CI, récupération par live update, et revue post-incident qui attribue les actions de prévention.

Table des matières

• La nuit où le dashboard s'est éteint
  • Définir précisément le périmètre de la panne
  • Reproduire en éliminant les variables
• Lire les logs de la WebView, du natif et de l'OS
  • Associez chaque symptôme à sa preuve
  • Corrélez avant de filtrer
• Déboguer la couche Web et la couche native
  • Commencer par la WebView
  • Passez aux outils natifs quand les preuves l'indiquent
• Premiers contrôles : réseau, stockage et permissions
• Tests automatisés et CI comme systèmes d'alerte précoce
  • Testez la logique partagée et les shells
  • Bloquez les merges en cas d'échec
• Les Live Updates comme canal de récupération d'urgence
  • Utilisez un déploiement progressif contrôlé
• Analyse post-incident pour éviter le prochain
  • Utilisez cinq blocs concrets
  • Assignez le travail avant de clôturer l'incident

La nuit où le dashboard s'est éteint

Jeudi soir, les utilisateurs Android signalaient un dashboard vide, tandis que les utilisateurs d'Electron sur desktop continuaient de fonctionner normalement. La première hypothèse était une régression Android 14 ou WebView. Cet indice a resserré la recherche, mais n'a pas permis d'identifier la panne. Les utilisateurs affectés partageaient aussi un canal de release, un chemin de configuration en cache, un environnement API et une séquence particulière de requêtes vers le dashboard.

L'ingénieur d'astreinte a commencé par comparer les versions de WebView. Les résultats semblaient plausibles et ne menaient nulle part. Un dashboard vide peut provenir d'une exception de rendu, d'une réponse API vide, d'une requête rejetée, d'un token invalide, d'un feature flag ou d'une lecture du stockage qui empêche la restauration de session. Avant de modifier code, établissez quel binaire, bundle web, configuration et chemin backend les utilisateurs affectés ont reçu.

Définir précisément le périmètre de la panne

Commencez par la télémétrie de production, pas depuis le laptop d'un développeur. Les recommandations de Google sur les crashs Android et les ANR préconisent de filtrer les événements par appareil, système d'exploitation et fenêtre temporelle, puis d'utiliser logcat pendant la reproduction quand l'emplacement de la panne reste flou. (Guide de dépannage Android vitals de Google)

Récupérez ces champs pour une session affectée :

• Identité du build : Enregistrez la version de l'app native, l'ID du build, le hash du bundle web et l'horodatage de la release.
• Canal de distribution : Confirmez si l'utilisateur a reçu du contenu canary, bêta, en déploiement progressif ou stable.
• Contexte d'exécution : Notez la version Android ou iOS, le modèle d'appareil, le type de réseau, l'état des permissions et si l'app a repris depuis l'arrière-plan.
• Dernière action réussie : Préservez la séquence de taps, la requête, le statut de la réponse et le résultat visible exacts.
• Instantané de la configuration : Comparez l'URL de base API, les feature flags, les paramètres d'authentification et la configuration des plugins avec un appareil fonctionnel.

Capacitor garde la version native distincte du contenu web exécuté dans la WebView. Deux utilisateurs peuvent partager un binaire installé depuis un store tout en recevant des bundles JavaScript différents. Ils peuvent aussi partager un bundle web tout en utilisant des plugins natifs différents. Electron exige la même vérification sur le manifeste de la release, la version du processus principal, le bundle du renderer et le canal de mise à jour. Les métadonnées du package renderer ne suffisent pas à établir ce que l'utilisateur a réellement exécuté.

Reproduire en éliminant les variables

Après avoir collecté les identifiants, classez l'incident comme canary uniquement, progressif ou déploiement complet. Un échec limité au canary pointe vers un bundle, un flag ou une affectation de canal ciblés. Un échec en déploiement progressif suggère un problème de logique de sélection d'audience ou d'appareil. Un échec après déploiement complet augmente la priorité de la configuration partagée, du comportement backend et de la compatibilité native.

Comparez l'appareil affecté à un appareil fonctionnel. Vérifiez les versions des plugins natifs, le hash web, le canal, l'environnement API, l'état d'authentification et les permissions accordées. Rejouez la dernière séquence d'actions de l'utilisateur en local avant de recourir à un émulateur. Si un flag contrôle l'échec, gardez les autres variables constantes et isolez le comportement de ce flag par dichotomie.

Règle pratique : Ne qualifiez pas une reproduction de « même bug » tant que le build ID, le canal, le bundle web, le système d’exploitation et la configuration ne correspondent pas.

L’incident sur le dashboard Android a reposé sur la correction de la configuration. L’équipe a comparé les instantanés, confirmé que le binaire natif était valide et vérifié que le WebView et le dashboard code n’avaient pas changé. Les clients en production demandaient un environnement avec un identifiant de staging, car l’invalidation du cache précédente n’avait pas atteint tous les clients mobiles. Les travaux de récupération ont donc porté sur la correction de la configuration, la définition des en-têtes d’invalidation de cache appropriés et la vérification du purge du CDN depuis les régions et chemins clients affectés.

Cette séquence est importante, car une commande de purge réussie ne prouve pas que chaque utilisateur peut récupérer la valeur corrigée. Vérifiez les réponses du CDN, l’âge du cache, les hashes du bundle ou de la configuration, ainsi qu’une session client fraîche avant de déclarer la récupération. Un rebuild natif aurait ajouté du temps de déploiement sans modifier l’artefact à l’origine de l’échec.

Appliquez la même rigueur pour les incidents futurs : identifier l’artefact de l’utilisateur, localiser la surface de défaillance, éliminer les différences environnementales, puis déboguer code. Un guide de réponse aux incidents pour les équipes mobiles doit conserver ces vérifications à côté du runbook d’astreinte, notamment les requêtes de télémétrie, la responsabilité du déploiement progressif, la vérification de la purge et la décision d’utiliser un live update lorsque le binaire natif n’est pas le composant défaillant.

Lire les logs de la WebView, du natif et de l'OS

Une application CapacitorJS ou Electron génère des preuves à plusieurs niveaux, et chaque niveau répond à une question différente. La WebView peut afficher des exceptions JavaScript et des requêtes échouées, mais elle n’expliquera pas chaque échec de plugin. Les logs natifs exposent le comportement du bridge et du cycle de vie, tandis que le système d’exploitation enregistre la pression mémoire, les refus de permissions et la terminaison des processus que les code de l’application peuvent ne jamais observer.

Associez chaque symptôme à sa preuve

Au niveau WebView, collectez les erreurs de console, les rejets de promesses non gérés, les événements de navigation, les URL des requêtes, les statuts de réponse et les durées des requêtes. Un rejet silencieux de plugin est particulièrement dangereux. L’interface peut continuer à s’afficher alors qu’une opération de caméra, de système de fichiers, de stockage sécurisé ou de notification a déjà échoué.

Le couche native contient la sortie logcat Android, les os_log logs iOS, les exceptions du pont de plugins, les événements de cycle de vie des activités ou des view controllers, et les traces de crash natifs. Electron ajoute le flux de logs du processus principal, les événements de mise à jour automatique, les échecs de création de fenêtre et les messages IPC. Une erreur du renderer n’apparaît pas forcément dans le processus principal, et un crash du processus principal n’est pas visible dans la console du renderer.

Le couche système explique les événements hors du contrôle de l’application. Recherchez la pression mémoire, la terminaison en arrière-plan, les restrictions de batterie, les permissions refusées, les processus tués et les rapports de crash système. Cette couche explique souvent un « crash aléatoire » qui n’a aucune pile JavaScript utile.

Corrélez avant de filtrer

Utilisez un ID de requête ou d’opération partagé entre la WebView, le pont natif, le backend et le sink de logs central. Ajoutez l’ID avant le début d’une action utilisateur, puis conservez-le tout au long de la requête réseau et du callback natif. Corrélez les horodatages dans un format cohérent, tenez compte de la dérive de l’horloge de l’appareil et filtrez le bruit du framework uniquement après avoir conservé l’événement d’origine.

Stockez les mêmes champs contextuels dans chaque couche : version de l’app, hash du bundle web, canal, appareil, OS, session et état des feature flags. Une collecte centralisée permet de comparer une tentative de reproduction avec les preuves de l’utilisateur, plutôt que de les remplacer par des suppositions. Un kit d’analyse de logs pour le débogage mobile doit vous aider à rechercher ces champs sans obliger les ingénieurs à collecter des captures d’écran sur chaque appareil.

Déboguer la couche Web et la couche native

Déboguez la couche responsable du symptôme. Un écran figé qui répond encore aux événements de cycle de vie natif vient généralement du WebView. Une fin de processus, une exception de plugin ou un échec au démarrage relève des outils natifs ou du processus principal Electron. Sauter d’une couche à l’autre sans cette règle de routage crée de l’activité sans isoler la cause.

Commencer par la WebView

Sur Android, connectez un build Capacitor débogable à Chrome et ouvrez chrome://inspect. Inspectez la console, le panneau réseau, le stockage et la chronologie des performances. Sur iOS, utilisez l’inspecteur Web de Safari avec l’appareil ou le simulateur connecté. Pour Electron, attachez-vous au renderer via son port DevTools ou appelez BrowserWindow.webContents.openDevTools() pendant l’investigation.

Les traces de pile en production ne sont utiles que si elles se relient au code source. Uploadez et conservez les source maps pour chaque bundle web, puis vérifiez que l’artefact de symbolication correspond exactement au hash du bundle. Ajoutez un intercepteur de console contrôlé pour les opérations critiques, mais évitez de journaliser les identifiants, les tokens ou les données personnelles. Capturez plutôt les noms d’opérations, les IDs de requête, les classes de réponse et les transitions d’état.

Passez aux outils natifs quand les preuves l'indiquent

Filtrez le Logcat d’Android Studio par le package de l’application, puis reproduisez le problème avec la séquence d’actions la plus courte possible. npx cap run android --livereload réduit la boucle d’itération pour les modifications WebView, mais ne valide pas l’artefact natif empaqueté. Sur iOS, exécutez depuis Xcode et utilisez la fenêtre Devices pour les logs de l’appareil. Le Time Profiler d’Instruments aide pour les charges CPU soutenues, tandis qu’Allocations aide à identifier la croissance mémoire.

Electron a deux cibles de débogage. Utilisez les DevTools du renderer pour le DOM, le JavaScript et le comportement réseau. Utilisez --inspect ou --inspect-brk pour le processus principal, et conserve sa sortie stderr lors des tests de démarrage et de mise à jour automatique.

Orientez-vous selon le symptôme. Les problèmes d’interface commencent dans le WebView. Les terminaisons natives commencent dans Android Studio ou Xcode. Les échecs de démarrage Electron commencent dans le processus principal.

Une explication utile de l’importance de cette distinction figure dans le modèle de bridge natif et WebView de Capacitor. Le bridge est une frontière, pas une seule surface de débogage. Traitez-l’ainsi, et chaque ligne de log a plus de chances de répondre à votre question.

Premiers contrôles : réseau, stockage et permissions

Les équipes vérifient souvent d’abord API car les erreurs réseau semblent techniques et familières. Cette habitude passe à côté des pannes causées par un état obsolète, des déclarations de permissions modifiées ou une mise à niveau de la plateforme qui a altéré le comportement du sandbox. La vérification la plus rapide dépend du domaine de la panne.

Pour les problèmes de stockage, storage.estimate() Capacitor La rotation de la clé de chiffrement des préférences peut révéler une pression sur le quota, mais ne diagnostiquera pas tous les problèmes de base de données. Testez un bac à sable applicatif nettoyé manuellement, puis comparez le comportement avec le profil existant. La rotation de la clé de chiffrement des préférences peut rendre des valeurs auparavant valides illisibles, tandis que le journal write-ahead de SQLite peut laisser un état endommagé après un arrêt brutal. Les applications Electron peuvent aussi sembler perdre des données lorsqu'une mise à jour du système d'exploitation modifie le userData chemin.

Les permissions méritent la même attention. Les descriptions d'utilisation iOS doivent correspondre à la capacité demandée. Le comportement des permissions Android peut changer après des modifications de SDK, et les prompts de notification peuvent entrer en concurrence avec l'initialisation au démarrage à froid. Le gestionnaire de permissions d'Electron peut rejeter une demande avant que le renderer ne reçoive une explication utile.

Si un utilisateur dit « ça marchait hier », vérifiez le stockage et les permissions avant de supposer que le réseau a changé.

Tests automatisés et CI comme systèmes d'alerte précoce

La CI permet de détecter les régressions au moindre coût lorsqu'elle teste l'artefact que les utilisateurs exécuteront. Une suite de tests au vert sur un serveur de développement ne prouve pas que le package Android signé, l'archive iOS ou l'installeur Electron peut démarrer, charger son bundle et effectuer une véritable opération authentifiée.

Testez la logique partagée et les shells

Utiliser Vitest pour la logique web partagée et Jest pour le comportement du processus principal d'Electron. Pour les plugins Capacitor, testez séparément le contrat JavaScript et l'implémentation native, puis ajoutez une couverture d'intégration pour les refus de permission, le matériel indisponible, les réponses malformées et les interruptions de cycle de vie.

Playwright peut tester un bundle web compilé. Pour Electron, utilisez Playwright Electron ou un test shell équivalent sur le binaire packagé, et pas seulement le renderer servi par un processus de développement local. Le test du binaire packagé permet de détecter les assets manquants, les chemins incorrects, les erreurs de signature et les hypothèses de démarrage que les tests de navigateur masquent.

La couverture des appareils doit refléter votre base installée réelle. BrowserStack ou Sauce Labs peuvent tester un ensemble délibérément choisi de profils d'appareils, de systèmes d'exploitation, d'états de permissions et de conditions réseau. L'objectif n'est pas d'avoir la matrice la plus grande, mais une couverture représentative des échecs.

Bloquez les merges en cas d'échec

Ajoutez des vérifications explicites pour :

• Modifications du bundle : Rejetez les écarts de taille de bundle inattendus et les source maps manquantes.
• Alignement natif : Détecter les écarts de version des plugins et les incompatibilités minSdkVersion réglages.
• Intégrité des artefacts : Vérifiez les signatures, l’identité du package, les assets intégrés et les manifests de release.
• Comportement au démarrage : Lancez l’app packagée et effectuez une requête authentifiée sur un endpoint.
• Comportement des mises à jour : Installez un bundle plus ancien, appliquez la mise à jour candidate, redémarrez et confirmez le comportement du rollback.

Publiez chaque résultat via un contrôle de statut GitHub afin qu'un signal rouge bloque la fusion. Un build qui passe les tests unitaires mais échoue à la vérification de l'artefact signé doit être considéré comme un échec, et non comme « presque vert ».

Le configuration de l'intégration continue pour les releases Capacitor est utile pour intégrer ces contrôles dans un pipeline reproductible. La CI ne remplace pas la télémétrie de production, mais elle réduit le nombre de défauts qui atteignent le staging et limite les inconnues pour les ingénieurs d'astreinte lors d'un incident.

Les Live Updates comme canal de récupération d'urgence

Une régression en production ne nécessite pas toujours un nouveau build natif. Si le défaut se trouve dans le JavaScript, le CSS, le texte, la configuration ou un autre asset web, un live update peut restaurer le parcours utilisateur pendant que l'équipe prépare une release appropriée. Cela fait de la livraison par live update un canal de récupération opérationnel, et non un simple confort pour des changements cosmétiques.

L'exigence de sécurité, c'est le contrôle. Utilisez des canaux nommés distincts pour les audiences canary, beta et stable. Gardez l'ID de l'app native et les contraintes de runtime compatibles explicites, et enregistrez quel bundle chaque audience reçoit. Un live update ne peut pas ajouter une permission native, remplacer un plugin natif, modifier le processus principal Electron ou réparer une erreur qui survient avant l'initialisation de l'updater. Ces cas nécessitent toujours une release via un store ou un installateur.

Utilisez un déploiement progressif contrôlé

Un processus d'urgence doit ressembler à ceci :

1. Confirmez le périmètre : Identifiez les versions natives, les canaux, les hashs de bundle et les signaux d'échec affectés.
2. Préparez le patch minimal : Modifiez uniquement le comportement web nécessaire pour rétablir le chemin défaillant.
3. Ciblez une audience canary : Envoyez le bundle à un canal contrôlé plutôt qu'à toutes les installations.
4. Surveillez la télémétrie : Vérifiez les signaux de crash, de chargement, de requête et d'échec de mise à jour pour la cohorte affectée.
5. Promouvez ou effectuez un rollback : Élargissez uniquement si les signaux restent sains. Revenez en arrière immédiatement si le patch provoque une nouvelle erreur.

Le rollback automatique doit s’appuyer sur des seuils explicites de taux de crash ou d’échec de chargement, définis par l’équipe. Un rollback ne protège les utilisateurs que si le mécanisme de mise à jour peut détecter l’échec et si le bundle précédent reste disponible. Conservez l’historique des versions et les garde-fous des canaux intacts afin que le support puisse expliquer ce qui s’est produit sur un appareil donné.

Capgo fournit une livraison de bundles web signés, des canaux ciblés, des logs par appareil, des métriques d’adoption et d’échec, l’historique des versions et une protection par rollback automatique pour les applications CapacitorJS et Electron. La règle de décision pratique est simple : utilisez un live update lorsque le correctif est limité au bundle web et que le mécanisme de mise à jour peut démarrer en toute sécurité ; planifiez un hotfix natif lorsque le runtime, un plugin, une permission, un package ou le processus principal est concerné. Le flux live-update de Capacitor décrit la limite entre ces deux approches.

Analyse post-incident pour éviter le prochain

Une rétrospective se justifie lorsqu’elle modifie le système. Rédigez-la tant que les logs, le contexte de déploiement et les décisions des opérateurs restent disponibles. Gardez le compte rendu factuel, sans recherche de coupable, et suffisamment précis pour qu’un autre ingénieur puisse identifier le garde-fou manquant sans reconstituer l’incident entier.

Utilisez cinq blocs concrets

Chronologie avec horodatages de télémétrie. Consignez la première requête échouée, la release concernée, la création de l'alerte, les étapes d'investigation, l'atténuation et le rétablissement. Pour l'incident du dashboard Android, la chronologie pourrait montrer que la vue vide est apparue après un déploiement de configuration, alors qu'iOS continuait de recevoir des réponses valides.

Mode de défaillance visible par l'utilisateur. Décrivez ce que les clients ont vécu, pas ce que le code a fait. « Les utilisateurs Android ont vu un dashboard vide après l'authentification » oriente mieux les intervenants que « Incohérence de clé API ». La première description pointe vers le parcours utilisateur cassé et les signaux qui auraient dû le détecter.

Lacune de détection. Indiquez pourquoi l'équipe l'a appris tardivement. Le monitoring des crashs est peut-être resté au vert car l'app s'est affichée correctement, alors qu'aucune alerte ne suivait les échecs de requêtes authentifiées ou les payloads de dashboard vides. Consignez le signal manquant et l'endroit où il aurait dû être émis.

Facteurs contributifs hors code. Listez la dérive de configuration, le comportement du cache, le timing du déploiement, les dépendances de service, les changements de permissions ou une race condition sur l'auto-update Electron. Ces domaines méritent des vérifications précoces car une défaillance en production peut survenir sans défaut dans le code de l'application.

Garde-fou préventif. Attribuez le test ou le contrôle qui aurait permis de détecter le problème. Par exemple : valider les credentials de production lors du déploiement, vérifier la configuration livrée par des clients représentatifs, ou ajouter un test de démarrage Electron packagé. Un garde-fou nécessite un responsable et une condition d'échec, pas seulement une phrase dans la rétrospective.

Les chemins de notification doivent faire partie de la même revue. Si les alertes e-mail n'atteignent pas l'équipe, consultez une ressource pratique sur comment éviter que les e-mails ne finissent en spam dans Gmail lors de la vérification des notifications, vérifiez ensuite le chemin de l'alerte. La création réussie du message ne prouve pas qu'un opérateur a bien reçu l'alerte.

Assignez le travail avant de clôturer l'incident

Pour chaque bloc, nommez un responsable, une date d'échéance et une méthode de vérification. Réexaminez l'incident sous 24 heures, tant que les ingénieurs peuvent encore remettre en question les hypothèses de l'enquête. Ne clôturez un élément qu'après avoir exécuté avec succès le nouveau test, le dashboard, la vérification de configuration ou la règle de déploiement progressif.

Utilisez cette checklist finale :

• Avons-nous identifié le build natif et le bundle web exacts ?
• Avons-nous distingué les causes liées à code, la configuration, le déploiement, l'infrastructure et les dépendances ?
• La télémétrie a-t-elle montré l’échec visible par l’utilisateur, pas seulement les crashs ?
• Avons-nous testé le canal affecté ainsi qu'un canal fonctionnel ?
• Avons-nous ajouté un garde-fou qui échoue avant la mise en production ?
• Avons-nous documenté si le recours à live update ou à une release native était approprié ?
• Un responsable désigné a-t-il vérifié le correctif ?

Les plaintes des utilisateurs montrent pourquoi la revue doit couvrir plus que les crashs. Dans un audit de 6 634 apps, les échecs de paiement ont touché 28.6% des apps, la compatibilité des appareils 28.4%, les frictions UI et UX 25.4%, les problèmes d’abonnement 21.8%, et les erreurs de connexion 17.2%, while crashes ranked seventh at 10.3%. (L’audit de Bright App Data sur les plaintes d’applications mobiles) Un processus de dépannage qui se limite à la question « pourquoi l’application a-t-elle planté ? » peut passer à côté des pannes qui bloquent le paiement, la connexion ou l’utilisation normale du produit.

Les données de stabilité confortent le même modèl’opérationnel. Un benchmark place l’application médiane à 99,95 % de sessions sans crash, avec les applications les plus performantes à 99.99% et les applications moins performantes à 99,77 % ou moins. Il indique aussi un taux médian d’ ANR de 2,62 pour 10 000 sessions, un taux OOM de 1,12 pour 10 000 sessions, et les taux de gel de l’application 64 à 103 sur 10 000 sessions selon le niveau de qualité. (Le benchmark de stabilité mobile) Une grande stabilité laisse encore des pannes significatives. Les équipes ont besoin de télémétrie pour les requêtes échouées, les états vides, les blocages, les erreurs de mise à jour et autres symptômes visibles par l’utilisateur.

Un rapport de 2026 indique que les utilisateurs ont déposé 6 fois plus de plaintes sur les fonctionnalités de base cassées que de nouveautés, et rapporte que 15,4 % désinstallent après un seul crash, tandis que plus de la moitié abandonnent après 2 ou 3 crashs. (Le rapport 2026 sur les bases défaillantes des apps) La réponse est pragmatique : détecter largement, récupérer rapidement et transformer chaque incident en un contrôle testable.

Utiliser Capgo pour livrer des mises à jour signées de bundles web CapacitorJS et Electron via des canaux contrôlés, inspecter la télémétrie par appareil, et effectuer un rollback d'un correctif JavaScript défaillant sans attendre la validation d'un store. Connectez-l’à votre pipeline de release, définissez des audiences stable et canary, et testez le processus de récupération avant la prochaine panne du dashboard.