Erreurs de configuration Expo avec exemples pratiques : guide terrain pour développeurs

Introduction

Les erreurs de configuration Expo peuvent casser les builds, provoquer des plantages à l’exécution ou laisser fuiter des secrets dans le contrôle de code source. Ce guide de terrain relie des erreurs réelles à des exemples pratiques, des sorties attendues, des signaux d’échec et des étapes de récupération. L’accent est mis sur la sécurité opérationnelle : observer avant de changer, limiter le rayon d’impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter comment récupérer si l’état attendu n’est pas atteint.

Ce guide s’adresse aux développeurs, consultants DevOps et équipes techniques de startups utilisant Expo SDK 49 ou supérieur, le CLI EAS 3.x et Node 18 LTS. Il couvre la configuration Expo, les erreurs de configuration Expo, la validation Expo, le retour en arrière Expo et le dépannage Expo. Les domaines connexes comme React Native, Android et GitLab CI/CD apparaissent uniquement lorsqu’ils affectent les prérequis, la compatibilité, la sécurité, l’observabilité ou la récupération.

Chaque exemple utilise des espaces réservés explicites comme <racine-projet>, <identifiant-bundle> ou <votre-slug>. Ne collez jamais de véritables identifiants, jetons, clés privées ou identifiants de production dans un article ou un fichier de configuration.

Inventaire des versions et de l’environnement

Avant de toucher un fichier de configuration, saisissez l’état actuel. Exécutez des commandes en lecture seule depuis le CLI officiel ou l’API. Définissez le résultat attendu et le signal d’échec avant de faire tout changement.

Prérequis

Expo SDK 49 ou supérieur installé (npx expo --version renvoie 49.0.0 ou plus récent).
EAS CLI 3.x (npm install -g eas-cli@3).
Node 18 LTS ou plus récent (node --version renvoie v18.0.0 ou plus récent).
Dépôt Git avec arbre de travail propre (git status --porcelain ne renvoie rien).

Commandes d’inventaire en lecture seule

Exécutez ces commandes depuis <racine-projet> et enregistrez leur sortie avec horodatage :

# 1. Vérifier la version Expo
npx expo --version
# Attendu : 49.0.0 (ou votre version SDK)

# 2. Vérifier la version du CLI EAS
eas --version
# Attendu : eas-cli/3.0.0 linux-x64 node-v18.0.0 (ou similaire)

# 3. Afficher la configuration résolue sans modifier les fichiers
npx expo config --type public
# Attendu : objet JSON avec expo.name, expo.slug, expo.version, etc.

# 4. Lister tous les fichiers de configuration suivis par git
git ls-files | grep -E 'app\.(json|config\.(js|ts))|eas\.json|metro\.config\.js|babel\.config\.js'
# Attendu : chemins relatifs comme app.json, eas.json

Rayon d’impact et chemin de récupération

Tout changement dans app.json ou app.config.js peut affecter à la fois les builds de développement et de production. Avant de modifier, identifiez l’environnement concerné :

# Afficher les profils de build EAS sans lancer de build
eas build:list --platform all --limit 5 --json
# Attendu : tableau des builds passés avec noms de profils (ex. : « preview », « production »)

Pour limiter le rayon d’impact, faites les modifications dans une branche et testez avec un build de prévisualisation avant de fusionner vers main. Chemin de récupération : commitez l’ancienne configuration avant de la changer, puis lancez git diff pour voir exactement ce qui a changé. Si un build échoue, revenez sur le commit avec git revert <hash-commit> et relancez le build.

git checkout -b fix/expo-config-horodatage
# Faire le changement limité, puis comparer
git diff app.json
# Si le changement est plus large que prévu, réinitialisez le fichier :
git checkout -- app.json

Chemin de configuration sûr

Cette section parcourt une erreur courante : mettre un secret directement dans app.json. Nous montrons ensuite le chemin sûr en utilisant des variables d’environnement et app.config.js.

Erreur : secret codé en dur dans app.json

De nombreux développeurs ajoutent une clé API directement dans extra de app.json :

{
  "expo": {
    "name": "MonApp",
    "slug": "monapp",
    "extra": {
      "apiKey": "sk_live_1234567890abcdef"
    }
  }
}

Ce secret est commité dans git et visible par toute personne ayant accès au dépôt. Il peut aussi apparaître dans les projets natifs générés ou les journaux de build EAS.

Chemin sûr : app.config.js avec variable d’environnement

Remplacez app.json par app.config.js. Gardez app.json uniquement pour les métadonnées statiques, ou supprimez-le entièrement si app.config.js est complet.

Étape 1 : Supprimer le secret de app.json

{
  "expo": {
    "name": "MonApp",
    "slug": "monapp"
  }
}

Étape 2 : Créer app.config.js à la racine du projet

module.exports = ({ config }) => {
  const apiKey = process.env.MYAPP_API_KEY;
  if (!apiKey) {
    console.warn('MYAPP_API_KEY n’est pas défini ; utilisation d’un espace réservé');
  }
  return {
    ...config,
    extra: {
      ...config.extra,
      apiKey: apiKey || 'placeholder-key-for-development-only',
    },
  };
};

Étape 3 : Ajouter la variable d’environnement à votre shell ou aux secrets CI/CD

Ne stockez jamais la vraie clé dans un fichier. Pour le développement local, utilisez un fichier .env ignoré par git :

# .env (NE PAS COMMITER)
MYAPP_API_KEY=sk_live_1234567890abcdef

Chargez-le ensuite avec dotenv ou votre shell. Pour EAS Build, définissez le secret dans le tableau de bord EAS ou en utilisant eas secret:create :

eas secret:create --name MYAPP_API_KEY --value "sk_live_xxx" --scope project
# Attendu : Secret MYAPP_API_KEY créé pour le projet.

Étape 4 : Vérifier que la configuration résolue contient l’espace réservé, pas le vrai secret

Exécutez la résolution de configuration sans la variable d’environnement définie :

MYAPP_API_KEY= npx expo config --type public
# La sortie attendue inclut extra.apiKey = "placeholder-key-for-development-only"

Exécutez-la ensuite avec le vrai secret dans un shell local (mais n’imprimez pas toute la configuration si elle contient des données sensibles ; utilisez jq ou grep pour vérifier uniquement la clé) :

MYAPP_API_KEY=sk_live_test npx expo config --json | jq -r '.extra.apiKey'
# Attendu : sk_live_test

Étape 5 : Commiter et vérifier qu’aucun secret n’est dans l’historique git

git add app.config.js app.json .gitignore
git commit -m "Déplacer la clé API vers une variable d’environnement"
git grep 'sk_live_' $(git rev-list --all) || true
# Attendu : aucune sortie (secret introuvable)

Rayon d’impact et récupération : Passer de app.json à app.config.js affecte la résolution de configuration pour toutes les commandes (expo start, eas build, eas update). Si un build échoue après le changement, revenez sur le commit comme décrit précédemment et vérifiez que MYAPP_API_KEY est défini dans l’environnement de build.

Vérification et diagnostics

Après tout changement de configuration, vérifiez que l’application fonctionne encore en développement et que le build réussit. Les diagnostics doivent être en lecture seule et adaptés à la version.

Commandes de diagnostic après changement de configuration

# 1. Démarrer le serveur de développement avec journalisation
expo start --clear
# Attendu : un code QR apparaît ; appuyez sur « a » pour ouvrir sur Android, « i » pour iOS

# 2. Exécuter Expo doctor pour détecter les problèmes de dépendances et de configuration
npx expo-doctor
# Attendu : « Aucun problème détecté avec le projet ! » ou liste d’avertissements/erreurs

# 3. Vérifier les erreurs de schéma de configuration en préconstruisant les projets natifs dans un répertoire temporaire
npx expo prebuild --no-install --platform android
# Attendu : répertoire android/ généré sans erreurs ; ne pas commiter si vous utilisez CNG

# 4. Valider le profil de build EAS et calculer les identifiants
eas build --platform android --profile preview --non-interactive --no-wait
# Attendu : Build mis en file. Vérifiez le statut avec `eas build:list`

Interpréter les signaux d’échec

Si npx expo-doctor signale des versions incompatibles, mettez à jour les paquets avec npx expo install --fix et relancez. Si expo prebuild échoue, vérifiez que votre app.config.js renvoie un objet de configuration valide et que tous les fichiers référencés existent.

Exemple d’échec : chemin d’icône manquant

# app.json inclut "icon": "./assets/icone-manquante.png"
npx expo config --type public
# Avertissement : Impossible de trouver le fichier : ./assets/icone-manquante.png

Correctif : ajoutez le fichier ou supprimez le champ icon. Relancez ensuite la vérification.

Résumé des sorties attendues

Commande	Code de sortie attendu	Sortie clé
`npx expo --version`	0	Numéro de version
`npx expo config --type public`	0	JSON avec expo.name, expo.slug
`npx expo-doctor`	0 si aucun problème	« Aucun problème détecté »
`npx expo prebuild --no-install`	0 si succès	Répertoires natifs générés
`eas build --profile preview --no-wait`	0 si mis en file	URL du build

Modes d’échec et récupération

Cette section couvre les modes d’échec de configuration Expo les plus courants, comment les détecter et la récupération pas à pas.

Mode d’échec 1 : échec du build EAS en raison d’un app.json invalide

Symptôme : eas build échoue immédiatement avec une erreur d’analyse JSON ou de validation de schéma.

Détection :

eas build --platform android --profile preview
# Sortie : « Error: Invalid app.json: ... » ou « app.json: Unexpected token »

Récupération :

Valider la syntaxe JSON :

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

Vérifier le schéma avec npx expo config :

   npx expo config --type public
   # En cas d’erreur, corrigez le champ mentionné.

Relancer le build. Si vous utilisez app.config.js, ajoutez un try-catch pour journaliser les erreurs.

Mode d’échec 2 : variable d’environnement manquante dans EAS Build

Symptôme : Le build réussit mais l’application affiche un texte d’espace réservé ou les appels API échouent avec 401.

Détection : Inspectez les journaux de build pour l’avertissement imprimé par app.config.js (MYAPP_API_KEY n’est pas défini).

Récupération :

eas secret:list --scope project
# Vérifiez si MYAPP_API_KEY est présent
eas secret:create --name MYAPP_API_KEY --value "bonne-cle" --scope project
# Reconstruire :
eas build --platform android --profile production --no-wait

Vérifiez dans l’application en cours d’exécution que la bonne clé est utilisée. Pour les environnements non-production, utilisez un espace réservé.

Mode d’échec 3 : retour en arrière d’une mise à jour cassée

Vous avez publié une mise à jour OTA (via eas update) qui plante au démarrage. Vous devez revenir à une mise à jour précédente connue comme stable.

Détection : Les utilisateurs signalent des plantages ; vous pouvez vérifier l’historique des mises à jour :

eas update:list --branch production --limit 10
# Notez l’ID de mise à jour de la dernière version connue comme stable

Récupération : Republiez le commit connu comme stable sur la même branche :

git checkout <hash-commit-stable>
eas update --branch production --message "Retour à la version stable"
# Attendu : Mise à jour publiée sur la branche production

Ou pointez la branche vers une mise à jour précédente en utilisant le tableau de bord. Après le retour en arrière, demandez aux utilisateurs de forcer la fermeture et de rouvrir l’application.

Mode d’échec 4 : dérive de configuration entre environnements

Votre eas.json a des extra différents pour preview et production, et une valeur est manquante en production.

Détection : Comparez les configurations résolues pour différents profils :

eas config --profile preview --json | jq '.extra'
eas config --profile production --json | jq '.extra'

Récupération : Définissez des valeurs spécifiques à l’environnement dans eas.json ou dans les variables CI/CD. Mettez à jour la valeur manquante et relancez le build de production.

Liste de contrôle opérationnelle

Utilisez cette liste avant et après tout changement de configuration Expo. Remplacez les espaces réservés par vos valeurs réelles.

Avant le changement

[ ] Capturer l’état actuel : exécutez npx expo config --type public > config-avant.json et horodatez-le.
[ ] Enregistrer les versions d’Expo SDK et du CLI EAS : npx expo --version et eas --version.
[ ] S’assurer que l’arbre de travail est propre : git status --porcelain renvoie vide.
[ ] Créer une branche de fonctionnalité : git checkout -b changement-config-<date>.
[ ] Identifier le rayon d’impact : listez les profils EAS qui seront affectés (eas build:list ou inspectez eas.json).
[ ] Définir les signaux de succès et d’échec attendus (ex. : build mis en file, configuration résolue sans avertissements).

Pendant le changement

[ ] Faire un changement limité à la fois (ex. : mettre à jour le slug, ajouter un extra, changer l’icône).
[ ] Utiliser des espaces réservés au lieu de secrets dans les fichiers ; définir les valeurs réelles via l’environnement ou les secrets EAS.
[ ] Exécuter npx expo config --type public après le changement et différer contre config-avant.json pour confirmer uniquement les changements prévus.
[ ] Si vous utilisez app.config.js, ajoutez une journalisation pour les variables d’environnement manquantes (comme montré précédemment).

Vérification après le changement

[ ] Exécuter npx expo-doctor et résoudre toutes les erreurs.
[ ] Démarrer le serveur de développement et charger l’application sur un appareil (expo start --clear).
[ ] Déclencher un build de prévisualisation : eas build --platform android --profile preview --no-wait.
[ ] Vérifier les journaux de build pour des avertissements sur des fichiers manquants ou des champs invalides.
[ ] Si le build réussit, installer sur un appareil de test et vérifier le comportement modifié.

Préparation du retour en arrière

[ ] Connaître le dernier hash de commit stable : git log -1 --format=%H avant le changement.
[ ] Documenter la commande de retour exacte : git revert <hash-commit>.
[ ] Pour les mises à jour de production, noter le dernier ID de mise à jour stable avec eas update:list --branch production.
[ ] Tester le retour en arrière dans un environnement de staging avant qu’un incident ne l’impose.

Exemple d’entrée de liste remplie

Instantané avant changement : config-avant-2025-03-10T18-30.json enregistré par Priya Shah, responsable ingénierie.
Changement : déplacé apiKey de app.json vers app.config.js en utilisant la variable d’environnement MYAPP_API_KEY.
Vérification : npx expo config --json | jq -r '.extra.apiKey' renvoie placeholder-key-for-development-only quand la variable d’environnement n’est pas définie ; renvoie la valeur réelle quand elle est définie localement.
Vérification du build : eas build --platform android --profile preview a réussi, ID de build 12345abc-6789-def0-1234-56789abcdef0.
Retour en arrière : git revert 9f8e7d6c5b4a3210 et reconstruire si nécessaire.

Conclusion

Les erreurs de configuration Expo sont évitables lorsque chaque recommandation est versionnée, observable et réversible. Copier une commande sans vérifier les prérequis et la sortie attendue n’est pas une procédure opérationnelle. Les exemples de ce guide utilisent des espaces réservés explicites, des observations en lecture seule et des interventions minimales avec des chemins de récupération testés.

Comme prochaine étape, choisissez une vérification à faible risque pour votre configuration Expo : exécutez npx expo config --type public, comparez la sortie avec votre état attendu et lancez npx expo-doctor. Passez en revue les dépendances telles que la compatibilité de version React Native, les outils de build Android et les variables CI/CD.

Un flux de travail technique fiable rend l’échec visible, 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.