Comment corriger une page blanche dans votre application web

Une page blanche signifie presque toujours l'une de deux choses : le JavaScript de l'application a planté avant d'avoir rien dessiné, ou le JavaScript ne s'est jamais chargé. Ouvrez la console du navigateur (clic droit → Inspecter → Console), lisez la première erreur rouge, puis consultez l'onglet Réseau pour repérer les fichiers qui n'ont pas pu se charger. La plupart des causes sont une variable d'environnement manquante, un mauvais chemin de base, un build qui ne s'est pas terminé ou un plantage dans un composant.

Ce guide couvre les applications à page unique (SPA) construites avec React, Vue ou des frameworks similaires, y compris les applications créées par des générateurs d'IA, où les pages blanches sont les plus fréquentes.

Pourquoi la page est blanche

Une application à page unique moderne envoie au navigateur un fichier HTML presque vide, à peu près comme ceci :

<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 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 : faites un clic droit sur la page et choisissez Inspecter, ou appuyez sur F12 (Cmd+Option+I sur Mac). Allez dans l'onglet Console et actualisez la page.

Regardez la première erreur rouge ; les suivantes sont souvent des effets secondaires. Son contenu 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 générateur d'IA, collez-le directement dans le chat.

Étape 2 : Vérifier que les fichiers se sont chargés

Ouvrez l'onglet Réseau, cochez Désactiver le cache et actualisez. 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 fallback SPA) au lieu du script. La cause est la même : le fichier n'est pas là où la page l'attend.

Raisons fréquentes :

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, il s'agit de l'option base de vite.config ; dans Create React App, du champ homepage ; dans Next.js, de basePath. Il doit correspondre à l'endroit où l'application est réellement servie.

index.html obsolète. Les outils de build donnent aux fichiers des noms avec un hachage 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) permet de le confirmer. 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 ne s'est pas terminé ou n'a pas été déployé. Si le build a échoué, l'hébergeur peut servir un dossier de sortie ancien ou vide. Consultez le journal de build pour y trouver les erreurs.

Le mauvais dossier est publié. L'hébergeur doit servir le résultat du build (généralement dist ou build), et non le dossier source du projet. Servir les sources 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 frontend lisent souvent des réglages comme l'URL d'une API ou une clé publique au moment du build. Si une variable manque sur le build en ligne, du code comme createClient(undefined, undefined) lève une erreur immédiatement, et la page devient blanche.

Points à connaître :

• 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 intégrées au moment du build. Ajouter une variable après le build ne change rien tant que vous n'avez pas recompilé et redéployé.
• L'aperçu 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 que le frontend lit, 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 lorsqu'une variable manque.

Étape 4 : Corriger le plantage

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

• Données pas encore chargées. Un composant lit user.name avant que user ne soit arrivé. La correction consiste à afficher un état de chargement, ou à utiliser le chaînage optionnel (user?.name).
• Données vides. Un nouveau compte n'a aucun enregistrement, et le code suppose que la 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é.
• Une API réservée au navigateur utilisée pendant le rendu côté serveur, comme window ou localStorage dans un composant serveur de 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 limite d'erreur

Dans React, un seul composant qui plante peut démonter toute l'application, c'est pourquoi un petit bogue produit une page entièrement blanche. Une limite d'erreur (error boundary) est un composant qui intercepte les erreurs de rendu situées en dessous de lui et affiche un message de secours à la place.

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

Elle ne corrige pas le bogue, mais les visiteurs voient un message au lieu d'un écran blanc, et vous voyez où ça 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, il s'affiche mais est 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'existe 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 a id="app" et que le code cherche root, rien n'apparaît (et React journalise généralement une erreur).
• Vérifiez les extensions du navigateur. Essayez une fenêtre de navigation privée. Les bloqueurs de publicités bloquent parfois des scripts dont le nom contient analytics ou ads.

Page blanche seulement après l'actualisation d'une page ?

Si la page d'accueil fonctionne mais qu'actualiser /dashboard affiche une page blanche ou une 404, le serveur ne sait pas qu'il doit envoyer index.html pour les routes de l'application. C'est un problème de fallback 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 rouge est généralement la cause.
• Définir les variables d'environnement sans recompiler. Les variables du frontend sont figées au moment du build.
• Tester uniquement avec votre propre compte. Les plantages sur 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'élimine 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 lancer 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 é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 ramène le projet à son état antérieur. Voir Dépannage et Dépannage de la publication dans la documentation, ainsi que notre guide général sur le débogage d'une application créée avec l'IA.

Checklist pour une page blanche

• Lu la première erreur rouge dans la console
• Vérifié dans l'onglet Réseau les fichiers .js/.css qui renvoient une 404 ou du HTML
• Chemin de base conforme à 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 frontend définies sur le build en ligne, puis recompilé
• Plantage corrigé, y compris pour les comptes vides et les nouveaux comptes
• Limite 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