Comment corriger une page blanche dans votre application web

Une page blanche signifie presque toujours l’une de ces deux choses : le JavaScript de l’application a planté avant de dessiner quoi que ce soit, ou le JavaScript n’a jamais été chargé. Ouvrez la console du navigateur (clic droit → Inspecter → Console), lisez la première erreur en rouge, puis regardez l’onglet Réseau pour les fichiers qui n’ont pas pu se charger. Les causes les plus fréquentes sont une variable d’environnement manquante, un mauvais chemin de base, un build qui ne s’est pas terminé, ou un plantage dans un seul composant.

Ce guide couvre les applications monopages (SPA) construites avec React, Vue ou des frameworks similaires, y compris les applications créées par des outils d’IA, qui sont le cas le plus fréquent de pages blanches.

Pourquoi la page est blanche

Une application monopage moderne envoie au navigateur un fichier HTML presque vide, à peu près de cette forme :

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Le JavaScript construit ensuite toute la page à l’intérieur de cette div vide. Si le script ne se charge pas, ou s’il lève une erreur avant de s’afficher, la div reste vide et vous voyez du blanc. La page n’est pas « cassée » de façon visible ; elle n’a simplement jamais été dessinée.

C’est pourquoi la correction commence toujours dans les outils de développement, et non dans la page elle-même.

Étape 1 : lire la console

Ouvrez les outils de développement : clic droit sur la page et Inspecter, ou F12 (Cmd+Option+I sur Mac). Allez dans l’onglet Console et rechargez la page.

Regardez la première erreur en rouge ; les suivantes sont souvent des conséquences. Son message indique la cause :

Copiez le texte complet de l’erreur, y compris le nom du fichier et le numéro de ligne. Si vous utilisez un créateur d’applications par IA, collez-le directement dans le chat.

Étape 2 : vérifier que les fichiers ont été chargés

Ouvrez l’onglet Réseau, cochez Désactiver le cache, et rechargez. Regardez les requêtes pour les fichiers .js et .css.

• Statut 404 sur un fichier JavaScript : la page demande un fichier qui n’est pas sur le serveur.
• Statut 200 mais type text/html : le serveur a renvoyé une page (souvent index.html lui-même, à cause d’un repli SPA) au lieu du script. La cause est la même : le fichier n’est pas à l’endroit attendu par la page.

Raisons courantes :

Mauvais chemin de base. Si l’application est servie depuis un sous-dossier, comme exemple.com/app/, mais a été compilée pour charger ses fichiers depuis /assets/..., chaque requête de script échoue. Dans Vite, c’est l’option base de vite.config ; dans Create React App, c’est le champ homepage ; dans Next.js, c’est basePath. Il doit correspondre à l’endroit où l’application est réellement servie.

index.html obsolète. Les outils de build donnent aux fichiers un nom contenant un hash de contenu, comme index-a1b2c3.js. Après un nouveau déploiement, l’ancien fichier disparaît. Si un navigateur ou un CDN conserve encore l’ancien index.html en cache, il demande l’ancien fichier et n’obtient rien. Un rechargement forcé (Cmd+Shift+R ou Ctrl+Shift+R) confirme ce cas. La solution durable consiste à servir index.html avec un en-tête de cache court ou inexistant, tandis que les fichiers hachés sont mis en cache longtemps.

Le build n’a pas abouti ou n’a pas été déployé. Si le build a échoué, l’hébergeur peut servir un dossier de sortie ancien ou vide. Vérifiez les erreurs dans le journal de build.

Le mauvais dossier est publié. L’hébergeur doit servir le résultat du build (en général dist ou build), et non le dossier source du projet. Servir la source vous donne un index.html qui pointe vers /src/main.tsx, que les navigateurs ne peuvent pas exécuter.

Étape 3 : vérifier les variables d’environnement

Les applications front-end lisent souvent des réglages comme une URL d’API ou une clé publique au moment du build. Si une variable manque dans le build en ligne, du code comme createClient(undefined, undefined) lève une erreur immédiatement, et la page devient blanche.

À savoir :

• Dans Vite, seules les variables préfixées par VITE_ sont disponibles dans le code du navigateur, lues avec import.meta.env.VITE_NOM. Dans Create React App, le préfixe est REACT_APP_ ; dans Next.js, NEXT_PUBLIC_.
• Ces valeurs sont figées au moment du build. Ajouter une variable après le build ne change rien tant que vous ne refaites pas le build et le déploiement.
• La prévisualisation ou votre ordinateur peuvent avoir un fichier .env que le build de production n’a pas. Définissez les mêmes variables chez l’hébergeur.
• Tout ce qui porte ces préfixes finit dans le JavaScript public. Ne mettez que des valeurs publiques, jamais de clés secrètes.

Un test rapide : cherchez undefined à côté du nom d’un réglage dans l’erreur de la console, ou demandez :

L’application publiée affiche une page blanche. Liste toutes les variables d’environnement lues par le front-end, vérifie lesquelles manquent ou sont vides dans le build en ligne, et fais en sorte que l’application affiche un message d’erreur clair au lieu d’une page blanche quand l’une d’elles manque.

Étape 4 : corriger le plantage

Si la console affiche une erreur JavaScript classique, le code a planté pendant le rendu. Causes typiques dans les applications créées par IA :

• Données pas encore chargées. Un composant lit user.name avant que user soit arrivé. La solution est un état de chargement, ou le chaînage optionnel (user?.name).
• Données vides. Un nouveau compte n’a aucun enregistrement, et le code suppose qu’une liste contient au moins un élément.
• Forme de données inattendue. Une API a renvoyé un objet d’erreur au lieu de la liste attendue par le code.
• Un import manquant après qu’un fichier a été renommé ou déplacé.
• Utiliser une API réservée au navigateur pendant le rendu côté serveur, comme window ou localStorage dans un composant serveur Next.js.

Donnez à l’IA l’erreur complète, la page et le compte avec lequel vous étiez connecté :

La page Tableau de bord est blanche pour les nouveaux utilisateurs. Console : TypeError: Cannot read properties of undefined (reading 'map') à ProjectList.tsx:18. Elle fonctionne pour mon compte, qui a des projets. Corrige-la pour qu’un compte vide affiche « Aucun projet pour le moment », et vérifie un nouveau compte dans l’aperçu.

Étape 5 : ajouter une frontière d’erreur

Dans React, un seul composant qui plante peut démonter toute l’application, ce qui explique qu’un petit bug produise une page entièrement blanche. Une frontière d’erreur (error boundary) est un composant qui intercepte les erreurs de rendu en dessous de lui et affiche un message de secours à la place.

Ajoute une frontière d’erreur autour des routes principales qui affiche « Une erreur est survenue » avec un bouton Recharger, et enregistre l’erreur dans la console. Garde l’en-tête et la navigation en dehors, pour qu’ils restent affichés.

Elle ne corrige pas le bug, mais les visiteurs voient un message au lieu d’un écran blanc, et vous voyez où cela a cassé.

Étape 6 : aucune erreur, mais toujours blanc

Si la console est vide et que les scripts se chargent :

• Vérifiez l’onglet Éléments. Y a-t-il du contenu dans <div id="root"> ? Si oui, cela s’affiche mais reste invisible : texte blanc sur fond blanc, opacity: 0, display: none, ou un élément plein écran qui le recouvre.
• Vérifiez le routeur. Si aucune route ne correspond à l’URL courante et qu’il n’y a pas de route « introuvable », certains routeurs n’affichent rien. Ajoutez une route de repli qui affiche une page 404.
• Vérifiez le point de montage. Le code doit se monter dans un élément qui existe. Si index.html contient id="app" et que le code cherche root, rien n’apparaît (et React signale en général une erreur).
• Vérifiez une extension du navigateur. Essayez une fenêtre privée. Les bloqueurs de publicités bloquent parfois des scripts dont le nom contient analytics ou ads.

Page blanche seulement après un rafraîchissement ?

Si la page d’accueil fonctionne mais que le rafraîchissement de /dashboard affiche une page blanche ou un 404, le serveur ne sait pas qu’il doit envoyer index.html pour les routes de l’application. C’est un problème de repli de routage, traité dans comment corriger les erreurs 404 après déploiement.

Erreurs courantes

• Lire la dernière erreur au lieu de la première. La première ligne en rouge est généralement la cause.
• Définir les variables d’environnement sans refaire le build. Les variables du front-end sont figées au moment du build.
• Ne tester qu’avec votre propre compte. Les plantages sur un compte vide sont l’une des causes les plus fréquentes de page blanche.
• Supposer que le déploiement a réussi. Vérifiez le journal de build avant de déboguer le code.
• Accuser le cache du navigateur pour tout. Un rechargement forcé l’écarte en quelques secondes ; si la page reste blanche, c’est autre chose.

Pages blanches dans Mythex

Si l’aperçu est blanc, vérifiez d’abord que l’application tourne (ouvrez Code → terminal), puis demandez à Mythex de démarrer le bon serveur, cliquez sur Actualiser dans la barre d’outils de l’aperçu, ou utilisez /fix. Pour une URL publiée blanche, la documentation suggère d’attendre une minute et de forcer le rechargement, de vérifier que les variables d’environnement et la base de données ont bien été configurées avant la publication, et de contrôler votre quota d’hébergement. Rappelez-vous qu’une application publiée est un instantané : après une correction, publiez à nouveau. Si une modification est à l’origine du problème, Revenir à ce point sur la dernière bonne réponse restaure le projet. Voir Dépannage et Dépannage de la publication dans la documentation, et notre guide général sur le débogage d’une application créée par IA.

Liste de contrôle de la page blanche

• Lu la première erreur en rouge dans la console
• Vérifié dans l’onglet Réseau les fichiers .js/.css qui renvoient 404 ou du HTML
• Le chemin de base correspond à l’endroit où l’application est servie
• Build terminé, et le dossier du résultat du build est celui qui est publié
• Toutes les variables d’environnement du front-end définies sur le build en ligne, puis build refait
• Plantage corrigé, y compris pour les comptes vides et nouveaux
• Frontière d’erreur en place pour que les futurs plantages affichent un message
• Route de repli pour les URL inconnues
• Testé après un rechargement forcé et dans une fenêtre privée

Questions