Erreurs courantes avec React Native et leurs correctifs : guide pratique de dépannage

Introduction

React Native permet de créer des applications mobiles avec JavaScript, mais des erreurs peuvent survenir à chaque couche : bundling, exécution, modules natifs ou outils de build. Une approche méthodique transforme la panique en correction rapide : identifier l’environnement, reproduire l’erreur, apporter une seule modification et vérifier le résultat. Ce guide passe en revue les erreurs React Native courantes avec des commandes pratiques à copier-coller et des étapes de récupération.

Nous couvrons les flux de travail React Native CLI et Expo, car tous deux partagent de nombreux modes de défaillance, mais diffèrent par l’outillage. Chaque section comprend des diagnostics en lecture seule, le correctif minimal et une vérification. Utilisez des espaces réservés plutôt que de vraies informations d’identification dans toute commande que vous exécutez, et conservez un enregistrement des changements d’état pour faciliter le retour en arrière.

Inventaire des versions et de l’environnement

Avant de toucher au code, établissez la vérité terrain. De nombreuses erreurs sont des incompatibilités de versions déguisées.

Observations en lecture seule

Exécutez les commandes suivantes à la racine du projet et enregistrez la sortie :

node --version
npm --version
npx react-native --version

Exemple de sortie :

node: v18.17.1
npm: 9.6.7
react-native: npx: installed 1 in 2.3s
React Native version: 0.72.5

Pour les projets Expo, vérifiez :

npx expo --version

Inspectez également package.json pour react-native et les dépendances clés, et android/build.gradle pour la version du plugin Gradle Android et compileSdkVersion.

Variables d’environnement et chemins

Vérifiez que le SDK Android est correctement configuré (pour React Native CLI) :

echo $ANDROID_HOME
adb --version

Attendu : $ANDROID_HOME pointe vers un répertoire SDK valide, et adb renvoie une chaîne de version.

Si ANDROID_HOME n’est pas défini, ajoutez-le à votre profil shell (~/.bashrc ou ~/.zshrc) :

export ANDROID_HOME=$HOME/Library/Android/sdk  # exemple macOS
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Puis rechargez avec source ~/.zshrc (ou votre profil).

Pour iOS, vérifiez les outils en ligne de commande Xcode et CocoaPods :

xcode-select --version
pod --version

Si CocoaPods est manquant, installez-le avec sudo gem install cocoapods.

Portée des dégâts et récupération

Documentez l’état actuel dans un fichier local, par exemple env-snapshot-YYYYMMDD.txt, avec :

• Versions de Node, npm, React Native, Expo
• Plages de dépendances dans package.json
• Emplacement du SDK Android et version des outils de plateforme
• Tout changement récent des variables d’environnement ou des fichiers de projet natif

Cette capture devient votre référence de retour en arrière. Si un changement casse le build, annulez le changement spécifique avant de déboguer davantage.

Chemin de configuration sécurisé

Les erreurs de configuration sont parmi les plus courantes, surtout après une mise à niveau de React Native ou l’ajout de modules natifs. Suivez ce chemin pour modifier les paramètres en toute sécurité.

Étape 1 : Localiser la configuration actuelle

Pour la configuration du bundler Metro, inspectez metro.config.js :

cat metro.config.js

Pour Babel, vérifiez babel.config.js.

Pour les projets natifs, vérifiez android/build.gradle et ios/Podfile.

Étape 2 : Apporter une seule modification à la fois

Supposons que vous deviez ajouter la prise en charge des actifs SVG. Vous installeriez react-native-svg et le lieriez. Au lieu de deviner, suivez ces étapes :

npm install react-native-svg
cd ios && pod install && cd ..

Vérifiez l’installation en contrôlant package.json et Podfile.lock.

Si vous devez modifier la configuration Metro pour inclure des extensions d’actifs, apportez une modification minimale :

// metro.config.js
const { getDefaultConfig } = require('metro-config');

module.exports = (async () => {
  const {
    resolver: { assetExts }
  } = await getDefaultConfig();
  return {
    resolver: {
      assetExts: [...assetExts, 'svg']
    }
  };
})();

Redémarrez Metro avec npx react-native start --reset-cache.

Étape 3 : Vérifier et revenir en arrière

Après le changement, exécutez l’application et testez la fonctionnalité spécifique. Si des problèmes surviennent, annulez le fichier de configuration (utilisez le contrôle de version) et redémarrez Metro.

Pour un exemple de retour en arrière, supposons que vous avez ajouté svg à assetExts mais que cela a fait échouer un autre type d’actif. Exécutez :

git checkout metro.config.js
npx react-native start --reset-cache

Cela restaure l’état précédent.

Précaution : Protéger les secrets

Ne codez jamais en dur des clés API ou des jetons dans les fichiers de configuration. Utilisez des variables d’environnement ou un gestionnaire de secrets. Par exemple, dans React Native, vous pouvez utiliser react-native-config :

npm install react-native-config

Créez ensuite .env (ajoutez à .gitignore) :

API_URL=https://api.example.com

Accédez dans le code :

import Config from 'react-native-config';
const apiUrl = Config.API_URL;

Vérification et diagnostics

La vérification distingue une vraie correction d’une nouvelle tentative chanceuse. Définissez toujours le résultat attendu avant d’exécuter une commande.

Vérifier l’état du bundler

Démarrez Metro avec une journalisation verbeuse :

npx react-native start --verbose

Recherchez des lignes comme :

 BUNDLE  ./index.js

Si vous voyez une erreur, capturez la trace de pile complète.

Tester un composant minimal

Créez un écran temporaire avec un composant simple pour isoler les problèmes :

// tempTest.js
import React from 'react';
import { View, Text } from 'react-native';

export default function TempTest() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Test OK</Text>
    </View>
  );
}

Importez ceci comme route initiale. S’il s’affiche, le problème vient probablement de votre composant personnalisé ou de vos données.

Utiliser le débogueur React Native

Pour les erreurs d’exécution, ouvrez le menu développeur dans l’application (Cmd+D sur iOS, Cmd+M sur émulateur Android) et sélectionnez « Debug ». Utilisez Chrome DevTools ou React Native Debugger pour inspecter les journaux et l’état.

Pour Android, vérifiez les journaux de l’appareil :

adb logcat

Filtrez pour les erreurs React Native :

adb logcat *:S ReactNative:V ReactNativeJS:V

La sortie attendue comprend les journaux de console JS et les erreurs de boîte rouge.

Vérifications automatisées

Exécutez le linting et les tests avant et après les changements :

npm run lint
npm test

Exemple de sortie réussie :

PASS  __tests__/App.test.js
  renders correctly
    ✓ renders correctly (312 ms)

Modes de défaillance et récupération

Voici les modes de défaillance courants, leurs symptômes, causes et correctifs étape par étape.

1. Metro Bundler « Unable to resolve module »

Symptôme : Le build échoue avec une erreur comme :

Unable to resolve module `./src/components/Button` from `src/screens/Home.js`

Cause probable : Chemin d’importation incorrect, extension de fichier manquante ou cache obsolète.

Correctif :

• Vérifiez que le fichier existe et que le chemin est correct (sensible à la casse sur CI Linux).
• Videz le cache Metro : npx react-native start --reset-cache.
• Supprimez node_modules et réinstallez si une dépendance est manquante :

rm -rf node_modules
npm install

Vérifier : Relancez le build et confirmez que le module se résout.

2. Échec du build Android : « Could not find com.android.tools.build:gradle »

Symptôme : La synchronisation Gradle échoue avec un plugin manquant.

Correctif : Assurez-vous que le dépôt Maven Google est dans android/build.gradle :

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.2")
    }
}

Puis exécutez :

cd android && ./gradlew clean && cd ..

Vérifier : ./gradlew assembleDebug se termine avec succès.

3. Échec de l’installation des pods iOS

Symptôme : pod install échoue avec « CocoaPods could not find compatible versions for pod 'React-Core' ».

Correctif :

• Supprimez Podfile.lock et le dossier Pods.
• Exécutez pod repo update et pod install --repo-update.
• Si cela échoue toujours, vérifiez ios/Podfile pour la version de plateforme. Assurez-vous qu’elle correspond aux exigences de React Native (généralement platform :ios, '12.4' ou supérieur).

Vérifier : pod install se termine et l’application se construit dans Xcode.

4. « Invariant Violation: requireNativeComponent: 'RNSVGPath' was not found in the UIManager »

Symptôme : Erreur de boîte rouge à l’exécution pour un composant natif.

Correctif : Généralement un problème de liaison. Pour React Native 0.60+, l’autolinking devrait fonctionner. Sinon, liez manuellement :

• Android : vérifiez que settings.gradle inclut la bibliothèque.
• iOS : exécutez cd ios && pod install && cd ...
• Reconstruisez l’application : npx react-native run-ios ou npx react-native run-android.

Vérifier : Le composant s’affiche sans erreur.

5. « Unable to load script. Make sure you're either running a Metro server or that your bundle 'index.android.bundle' is packaged correctly for release »

Symptôme : L’application affiche cette erreur au démarrage, souvent sur un appareil physique.

Correctif pour le débogage :

• Assurez-vous que Metro est en cours d’exécution (npx react-native start).
• Sur l’appareil, définissez l’hôte du serveur de débogage sur l’IP de votre machine : dans le menu développeur, « Settings » > « Debug server host & port for device », saisissez 192.168.1.100:8081 (remplacez par votre IP).
• Alternativement, exécutez adb reverse tcp:8081 tcp:8081 pour Android via USB.

Correctif pour la release :

• Bundlez le JS dans l’APK/IPA :

npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res

Puis reconstruisez la release.

Vérifier : L’application se charge sans dépendance réseau.

Principes de récupération

• Gardez toujours une capture des configurations fonctionnelles.
• Utilisez le contrôle de version et faites des commits avant de faire des changements risqués.
• Si un correctif introduit un nouveau problème, revenez immédiatement en arrière et analysez plus tard.

Liste de contrôle des opérations

Utilisez cette liste avant et après tout changement pour éviter les erreurs courantes et assurer la récupérabilité.

Chaque élément a un responsable unique et une fréquence claire. Ajustez les responsables à votre équipe, mais gardez la responsabilité explicite.

Pièges courants et comment les éviter

De nombreuses erreurs répétées proviennent de l’omission des vérifications d’environnement ou des couches de cache.

Piège 1 : Ignorer les incompatibilités de versions

Pourquoi cela arrive : Copier des commandes de tutoriels obsolètes ou mélanger des versions de React Native après une mise à niveau.

Comment éviter : Vérifiez toujours npx react-native --version et consultez l’assistant de mise à niveau officiel pour votre version cible. Ne mélangez jamais du code natif de différentes versions de React Native.

Récupération : Si une incompatibilité de version a causé un échec de build, revenez à un commit connu comme bon, puis mettez à niveau par étapes en utilisant npx react-native upgrade.

Piège 2 : Ne pas vider les caches

Pourquoi cela arrive : Les caches du bundler Metro et de Gradle/Pod deviennent obsolètes après des changements de dépendances.

Comment éviter : Après avoir changé les dépendances, exécutez :

watchman watch-del-all
rm -rf node_modules && npm install
cd android && ./gradlew clean && cd ..
cd ios && pod deintegrate && pod install && cd ..

Récupération : Si vous oubliez et rencontrez des erreurs de bundling étranges, exécutez la séquence de nettoyage des caches ci-dessus avant un débogage plus approfondi.

Piège 3 : Coder en dur les secrets

Pourquoi cela arrive : Le prototypage rapide conduit à des clés intégrées dans le code, puis oubliées.

Comment éviter : Utilisez des variables d’environnement dès le premier jour. Ajoutez .env à .gitignore et utilisez un gestionnaire de secrets pour la production.

Récupération : Si un secret a été commité, révoquez-le immédiatement, faites tourner les informations d’identification et nettoyez l’historique git en utilisant un outil comme git-filter-repo. Ensuite, mettez en place une injection d’environnement correcte.

Piège 4 : Sauter la vérification après les correctifs

Pourquoi cela arrive : Pression temporelle ; l’erreur disparaît, donc on suppose qu’elle est corrigée.

Comment éviter : Exécutez toujours la commande ou le test spécifique qui échouait auparavant. Pour les erreurs d’interface utilisateur, testez manuellement l’écran. Pour les erreurs de build, reconstruisez à partir d’un état propre.

Récupération : Si un correctif a des effets secondaires indésirables, utilisez votre capture d’environnement et le contrôle de version pour revenir en arrière, puis abordez le problème avec un changement plus petit.

Piège 5 : Utiliser un Watchman global qui entre en conflit

Pourquoi cela arrive : Plusieurs projets React Native avec des versions ou des permissions de watchman différentes provoquent l’échec de la surveillance des fichiers.

Comment éviter : Utilisez un watchman local au projet ou assurez-vous que watchman est à jour :

brew upgrade watchman   # macOS

Récupération : Si des erreurs watchman apparaissent, exécutez watchman watch-del-all et redémarrez Metro.

Conclusion

Les erreurs React Native sont rarement mystérieuses une fois que vous les tracez à leur couche : environnement, configuration, bundling ou build natif. Ce guide vous a donné des commandes concrètes et des listes de contrôle pour diagnostiquer et corriger les problèmes courants. La clé est la discipline : observez d’abord, changez une chose à la fois, vérifiez et gardez un chemin de retour en arrière.

Commencez par une vérification à faible risque de cet article, comme exécuter npx react-native --version et documenter votre environnement. Ensuite, lorsque la prochaine erreur apparaîtra, vous aurez déjà une base de référence. N’oubliez pas de passer en revue les dépendances comme Expo, le SDK Android et les modules natifs dans votre routine de dépannage.

Un flux de travail fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la récupération avant qu’un incident ne force la décision.