Dépannage d'Expo avec exemples pratiques

Introduction

Expo est une puissante plateforme open source pour construire des applications React Native avec un flux de travail géré. Elle masque une grande partie de la complexité de configuration native, mais comme toute chaîne d'outils, elle peut échouer de manière confuse. Lorsqu'une build casse, qu'un serveur de développement refuse de démarrer ou qu'une application déployée plante, vous avez besoin d'une approche structurée pour passer du symptôme à une correction vérifiée.

Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui utilisent Expo en production ou en développement actif. Il fournit des flux de travail de dépannage pratiques combinant des vérifications en ligne de commande, la validation de configuration, l'analyse de journaux et des procédures de récupération. Chaque exemple inclut une commande concrète, la sortie attendue et les signaux d'échec à surveiller.

Le principe sous-jacent est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des valeurs de remplacement pour les secrets, vérifier les résultats et documenter comment récupérer si l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant de changer quoi que ce soit, vous devez savoir exactement ce que vous exécutez. De nombreux problèmes Expo sont causés par des incompatibilités de versions entre l'interface en ligne de commande Expo, le SDK Expo du projet, React Native et les outils natifs. Commencez par collecter l'état actuel de votre environnement.

Prérequis :

• Node.js installé (LTS recommandé)
• Gestionnaire de paquets npm ou yarn
• Répertoire du projet avec package.json
• Accès au terminal

Commandes d'observation en lecture seule :

Vérifiez la version de l'interface en ligne de commande Expo globalement et localement :

npx expo --version

Exemple de sortie attendue :

6.3.10

Vérifiez les dépendances clés du projet sans rien modifier :

npm list expo react-native react

La sortie attendue doit inclure les versions de chacun. Si npm list signale des paquets manquants ou invalides, c'est un signal fort de corruption des dépendances.

Vérifiez votre version de Node.js :

node --version

Vérifiez votre version de npm :

npm --version

Expo SDK 49 et versions ultérieures nécessitent généralement Node 16 ou plus récent. Si votre version de Node est inférieure au niveau requis, de nombreuses commandes échoueront avec des erreurs cryptiques comme Cannot find module 'node:path' ou SyntaxError: Unexpected token '??='.

Vérifiez votre branche git et les modifications récentes pour comprendre ce qui a pu changer :

git status

git log --oneline -5

Rayon d'impact et récupération : L'exécution de commandes en lecture seule n'a aucun rayon d'impact. Si vous découvrez une incompatibilité de versions, le plus petit changement justifié est généralement d'aligner les versions à l'aide de l'assistant de mise à niveau officiel d'Expo ou en réinstallant les dépendances. Avant d'apporter toute modification, validez votre état actuel ou notez-le afin de pouvoir y revenir.

Vérification après inventaire : Enregistrez les valeurs que vous trouvez. Par exemple, vous pourriez noter : « Expo CLI 6.3.10, SDK 49, React Native 0.72.6, Node v18.17.1, npm 9.6.7 ». Cela devient votre base de référence pour les comparaisons ultérieures.

Chemin de configuration sûr

Les problèmes de configuration sont des sources fréquentes de problèmes Expo. Le fichier manifeste app.json ou app.config.js contrôle la façon dont votre application est construite et exécutée. Une simple coquille ou un champ invalide peut empêcher le serveur de développement de démarrer ou faire échouer EAS Build.

Observation en lecture seule de votre configuration actuelle :

npx expo config --type public

Cette commande affiche la configuration publique résolue. La sortie attendue est un objet JSON avec des clés comme name, slug, version, ios, android, etc. Cherchez des valeurs nulles inattendues ou des champs manquants.

Pour une vue plus complète incluant les champs internes :

npx expo config --type introspect

Problèmes de configuration courants :

1. app.json invalide : Le fichier doit être un JSON valide. Une virgule de trop ou une accolade manquante provoquera une erreur d'analyse. Validez-le avec :

node -e "JSON.parse(require('fs').readFileSync('app.json', 'utf8')); console.log('Valid JSON')"

Sortie attendue : Valid JSON. Si vous voyez une erreur, corrigez la syntaxe JSON.

1. Icône ou écran de démarrage manquant : Si vos chemins icon ou splash sont incorrects, EAS Build peut échouer lors de la génération des ressources natives. Vérifiez que le fichier existe :

ls assets/icon.png assets/splash.png

S'il en manque un, remplacez-le par un fichier PNG valide et mettez à jour le chemin dans app.json.

1. Problèmes de schéma : Si vous utilisez des liens profonds, le champ scheme ne doit pas contenir de caractères spéciaux. Vérifiez-le avec :

npx expo config --type public | grep scheme

Apporter un changement sûr à la configuration :

Supposons que vous deviez changer le versionCode pour Android. D'abord, faites une sauvegarde de votre app.json :

cp app.json app.json.backup

Ensuite, modifiez le champ avec une nouvelle valeur entière.

Après le changement, vérifiez que la configuration se résout toujours :

npx expo config --type public > /dev/null && echo "Config OK"

Si vous obtenez une erreur, revenez en arrière à l'aide de la sauvegarde :

cp app.json.backup app.json

Puis examinez la syntaxe ou le type du champ.

Chemin de récupération : Gardez toujours la sauvegarde jusqu'à ce que vous ayez confirmé que l'application fonctionne en développement et, le cas échéant, qu'une nouvelle build réussit.

Vérification et diagnostics

Une fois que vous avez un environnement et une configuration stables, vous devez observer le comportement de l'application et diagnostiquer les problèmes. Expo propose plusieurs outils de diagnostic.

Démarrage du serveur de développement avec journalisation verbeuse :

npx expo start --verbose

Surveillez les lignes indiquant que le serveur est prêt, telles que :

Waiting on http://localhost:8081

Si vous voyez des erreurs comme Metro bundler encountered an error, notez le chemin du fichier et le message d'erreur.

Affichage des journaux de l'appareil :

Pour Android, vous pouvez utiliser adb (si les outils de plateforme sont installés) :

adb logcat -s ReactNativeJS

Pour iOS, utilisez la visionneuse de journaux intégrée de l'application Expo Go ou exécutez :

npx expo start --ios

Puis vérifiez le terminal pour les journaux JS.

Exécution d'une build de diagnostic :

Pour EAS Build, vous pouvez exécuter une build locale pour isoler les problèmes :

npx eas build --platform android --profile preview --local

Cela exécute la build sur votre machine, vous donnant un accès direct aux journaux. La sortie attendue inclut la progression de chaque étape : installation des dépendances, exécution de prebuild, compilation du code natif et production d'un artefact.

Vérification de la santé des dépendances :

npx expo-doctor

Cette commande vérifie les problèmes courants comme les versions incompatibles ou la configuration manquante. La sortie attendue est une liste de vérifications, chacune avec un statut de réussite ou d'échec. Par exemple :

✔ Check Expo config (app.json/ app.config.js)
✔ Check package.json
✔ Check dependencies for compatibility

Si une vérification échoue, elle listera le problème et suggérera souvent une correction.

Interprétation des signaux d'échec :

• "Unable to resolve module" signifie qu'une dépendance est manquante ou incorrectement référencée. Vérifiez vos imports et package.json.
• "Invariant Violation: Native module cannot be null" signifie souvent qu'un module natif n'est pas correctement lié. Dans Expo Go, certains modules ne sont pas pris en charge ; vous pourriez avoir besoin d'une build de développement.
• Les erreurs de bundling qui mentionnent un fichier spécifique indiquent une erreur de syntaxe ou une fonctionnalité de langage non prise en charge.

Étape de vérification après toute correction : Après avoir apporté un changement, effacez le cache du bundler Metro et redémarrez :

npx expo start --clear

Puis rechargez l'application et vérifiez si l'erreur a disparu.

Modes d'échec et récupération

Comprendre les modes d'échec courants et avoir un plan de récupération est essentiel. Voici quelques problèmes fréquents et comment récupérer.

1. Incompatibilité de versions de dépendances

Symptôme : Vous voyez des erreurs comme TypeError: Cannot read property 'foo' of undefined ou The native module X doesn't exist après la mise à jour des paquets.

Pourquoi cela arrive : Vous avez mis à niveau un paquet mais pas les autres, ou vous avez un mélange de versions du SDK Expo.

Récupération :

npx expo install --fix

Cette commande tente d'aligner les dépendances avec le SDK Expo installé. Si cela échoue, modifiez manuellement package.json pour utiliser les versions recommandées par npx expo install pour chaque paquet, puis exécutez :

npm install

et effacez le cache :

npx expo start --clear

2. Corruption du cache du bundler Metro

Symptôme : Le serveur de développement ne détecte pas les changements, ou vous voyez des erreurs obsolètes même après avoir corrigé le code.

Pourquoi cela arrive : Le cache Metro peut devenir incohérent.

Récupération :

npx expo start --clear

Si cela ne fonctionne pas, supprimez manuellement les répertoires de cache :

rm -rf node_modules/.cache .expo

Puis réinstallez et redémarrez :

npm install
npx expo start

3. Erreur de configuration EAS Build

Symptôme : eas build échoue avec un message concernant eas.json ou des identifiants manquants.

Pourquoi cela arrive : eas.json peut avoir des profils invalides ou des champs manquants.

Récupération : Validez eas.json avec :

npx eas build:inspect

Cela montre ce qui serait construit. Corrigez les erreurs dans eas.json, puis relancez la build.

4. Port 8081 déjà utilisé

Symptôme : npx expo start échoue avec Error: listen EADDRINUSE: address already in use :::8081.

Pourquoi cela arrive : Un autre processus occupe le port.

Récupération : Trouvez le processus et tuez-le (sur Linux/macOS) :

lsof -ti tcp:8081 | xargs kill

Sur Windows, utilisez :

netstat -ano | findstr :8081

puis taskkill /PID <PID> /F. Sinon, démarrez Expo sur un port différent :

npx expo start --port 8082

5. L'application plante sur l'appareil après la mise à jour

Symptôme : L'application fonctionne en développement mais plante en production après une nouvelle mise à jour OTA ou une build.

Pourquoi cela arrive : De nouveaux modules natifs ont été ajoutés mais le binaire mis à jour n'a pas été reconstruit, ou la mise à jour OTA contient du JS incompatible avec le binaire.

Récupération : Annulez la mise à jour OTA si possible. Pour EAS Update, vous pouvez republier un commit précédent. Pour les changements natifs, créez une nouvelle build avec eas build. En développement, testez avec une build de développement plutôt qu'Expo Go si vous utilisez du code natif personnalisé.

Pièges courants

Évitez ces erreurs fréquentes lors du dépannage d'Expo.

1. Ignorer les différences d'environnement : Ce qui fonctionne sur la machine d'un développeur peut échouer sur une autre en raison de la version de Node, des paquets globaux ou des variables d'environnement. Exécutez toujours les commandes d'inventaire des versions avant de supposer un bug.

1. Modifier plusieurs choses à la fois : Si vous modifiez à la fois le code et la configuration simultanément, vous ne pouvez pas identifier la cause. Faites un changement, testez, puis continuez.

1. Utiliser de vrais secrets dans les commandes de test : Lorsque vous testez des appels API ou des variables d'environnement, ne mettez jamais de vrais jetons ou mots de passe dans des commandes qui pourraient être journalisées ou partagées. Utilisez des valeurs de remplacement comme YOUR_API_KEY dans tous les exemples.

1. Ne pas vérifier la compatibilité avec Expo Go : De nombreuses bibliothèques avec du code natif ne fonctionnent pas dans Expo Go. Si vous voyez des erreurs concernant des modules natifs, passez à une build de développement.

1. Sauter le nettoyage du cache : Les caches obsolètes causent des erreurs mystérieuses. Intégrez --clear à votre routine face à des problèmes de bundling étranges.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle lors du dépannage d'Expo. Pour chaque élément, une personne doit être responsable de son exécution, et les résultats doivent être consignés dans le suivi des incidents ou le runbook de votre équipe. Révisez la liste de contrôle chaque semaine pour les incidents actifs ou mensuellement comme bilan de santé.

Après avoir terminé la liste de contrôle, mettez à jour l'enregistrement d'état du système avec la date, les valeurs observées et toute anomalie. Si une étape échoue, attribuez au responsable désigné l'enquête et documentez les étapes de récupération entreprises.

Conclusion

Le dépannage d'Expo devient gérable lorsque vous l'abordez systématiquement. Commencez par inventorier votre environnement et votre configuration, apportez de petits changements réversibles, vérifiez chaque étape avec des commandes concrètes et connaissez les modes d'échec courants et leurs récupérations. Utilisez la liste de contrôle opérationnelle pour assurer la cohérence de votre équipe.

N'oubliez pas qu'un flux de travail de dépannage fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Avec les exemples pratiques de ce guide, vous pouvez résoudre la plupart des problèmes Expo rapidement et en toute confiance.