Comment corriger les erreurs 404 après le déploiement de votre site ou application

Si votre application fonctionne en local mais que les pages renvoient 404 après déploiement, la cause la plus fréquente est l’absence de routage d’application monopage (SPA) : le serveur cherche un fichier nommé /dashboard qui n’existe pas, car cette route n’existe que dans le JavaScript. La solution est une règle de repli qui sert index.html pour les routes de l’application. Les autres causes sont des fichiers absents du résultat du build, des chemins sensibles à la casse, des différences de barre oblique finale, un mauvais chemin de base, et des routes d’API qui n’ont jamais été déployées.

Commencez par noter exactement quelle URL renvoie 404 et comment vous y êtes arrivé. Le schéma indique directement la cause.

Étape 1 : identifier le schéma

Pour voir le vrai code de statut, ouvrez les outils de développement (clic droit → Inspecter), allez dans l’onglet Réseau, rechargez, et regardez le statut de la première requête.

Étape 2 : ajouter le repli SPA

C’est le cas classique. Dans une application monopage React, Vue ou Svelte, le serveur ne dispose que de quelques fichiers réels : index.html et quelques fichiers JavaScript et CSS. Les routes comme /dashboard ou /projects/42 sont gérées par un routeur dans le navigateur.

• Cliquer sur un lien fonctionne : le routeur change l’URL et affiche la nouvelle page sans demander au serveur.
• Rafraîchir ou ouvrir un lien directement échoue : le navigateur demande /dashboard au serveur, qui n’a pas ce fichier, et renvoie 404.

La solution est une règle qui dit : si la requête ne correspond pas à un fichier réel, servir index.html avec le statut 200, et laisser le routeur prendre le relais. La méthode dépend de l’hébergeur (vérifiez la documentation actuelle, car les détails changent) :

Veillez à ce que la règle n’avale pas les vrais fichiers : une requête pour /assets/app.js doit toujours renvoyer le fichier JavaScript. Si elle renvoie index.html à la place, vous obtenez une page blanche avec l’erreur « Failed to load module script ». Voir corriger une page blanche.

Donnez aussi au routeur une route de repli pour que les URL qui ne correspondent à aucune page affichent une page « Page introuvable » conviviale au lieu de rien.

Si vous ne pouvez pas modifier la configuration du serveur, le routage par hash (URL du type /#/dashboard) évite le problème, car la partie après # n’est jamais envoyée au serveur. C’est un contournement, pas un premier choix : les URL sont moins jolies et moins bien reconnues par les moteurs de recherche.

Les frameworks qui génèrent les pages côté serveur ou au moment du build (Next.js, Astro, et similaires) disposent en général de vrais fichiers ou de routes serveur pour chaque page, ce problème y est donc moins courant. Leur équivalent est une page qui n’a jamais été générée au moment du build.

Étape 3 : vérifier ce qui a réellement été déployé

Si tout renvoie 404, le serveur ne sert probablement pas votre application compilée.

• Le bon dossier. L’hébergeur doit publier le résultat du build (généralement dist pour Vite, build pour Create React App, out pour un export statique Next.js), et non la racine du projet.
• Le build a bien tourné. Lisez le journal de déploiement. Si le build a échoué, l’hébergeur n’a peut-être rien déployé, ou une ancienne version.
• index.html est au premier niveau du dossier publié, et non dans un sous-dossier.
• Le chemin de base correspond. Si l’application est servie depuis exemple.com/app/, elle doit être compilée avec ce chemin de base (base dans Vite, basename dans React Router), sinon chaque route et chaque ressource manque.

Étape 4 : corriger les fichiers manquants et les mauvais chemins

Quand les pages se chargent mais que les ressources renvoient 404 :

• Sensibilité à la casse. macOS et Windows considèrent souvent Logo.png et logo.png comme le même fichier. La plupart des serveurs Linux non. Faites correspondre chaque référence exactement au nom réel du fichier.
• Fichiers hors du build. Dans Vite, les fichiers de public/ sont copiés tels quels et référencés depuis la racine (/logo.png). Les fichiers importés dans le code sont intégrés au bundle. Un fichier situé ailleurs dans le projet peut ne pas être déployé du tout.
• Chemins relatifs. images/photo.jpg est résolu par rapport à l’URL courante, il casse donc sur /blog/post-1. Utilisez /images/photo.jpg.
• Fichiers envoyés enregistrés sur le disque local. Si les envois des utilisateurs sont écrits dans le dossier du serveur, ils disparaissent lors du déploiement d’une nouvelle version. Utilisez un vrai stockage de fichiers.

Étape 5 : gérer les barres obliques finales de façon cohérente

/about et /about/ sont deux URL différentes. Les hébergeurs diffèrent sur l’ajout ou la suppression de la barre finale, et une incohérence avec vos liens ou votre routeur peut produire des 404 ou des boucles de redirection. Choisissez un style, faites en sorte que vos liens l’utilisent, et configurez l’hébergeur pour rediriger l’autre forme vers celui-ci. La cohérence aide aussi les moteurs de recherche, qui sinon peuvent voir deux copies de chaque page.

Étape 6 : corriger les routes d’API qui renvoient 404

Si la page se charge mais que l’onglet Réseau montre des requêtes /api/... renvoyant 404 :

• Le back end n’est pas déployé. Un hébergeur statique ne sert que des fichiers ; un back end doit tourner quelque part.
• Le chemin est routé différemment en production. En développement, un proxy peut avoir transmis /api à un serveur séparé. En production, l’hébergeur a besoin d’une réécriture équivalente, ou le front-end doit appeler l’adresse réelle de l’API.
• Le repli SPA a intercepté la requête. Une requête API qui renvoie index.html avec le statut 200 signifie que la règle de repli est trop large. Excluez /api/* de cette règle.

Les requêtes de l’application publiée vers /api/orders renvoient 404, alors qu’elles fonctionnent dans l’aperçu. Vérifiez comment /api est routé dans l’aperçu et dans l’application publiée, et faites en sorte que le front-end publié atteigne le back end de la même manière.

Étape 7 : rediriger les anciennes URL

Si vous avez migré depuis un autre site ou restructuré vos pages, les anciennes URL encore utilisées par les personnes et les moteurs de recherche renverront 404. Ajoutez une redirection 301 (permanente) de chaque ancienne URL vers sa nouvelle adresse. Tenez une liste et testez un échantillon après le lancement. Notre guide sur la migration d’un site WordPress explique comment établir cette liste.

Étape 8 : vérifier le domaine

Si l’application fonctionne à l’adresse de l’hébergeur mais renvoie 404 sur votre domaine personnalisé, le domaine pointe peut-être vers le mauvais projet, ou l’hébergeur n’a pas encore rattaché le domaine à votre site. Vérifiez les enregistrements DNS et les paramètres de domaine chez l’hébergeur. Voir comment connecter un domaine personnalisé.

Rendre votre vraie page 404 utile

Certains 404 sont normaux : quelqu’un a mal tapé une URL. Rendez cette page utile :

• Un court message et un lien vers la page d’accueil et les sections clés
• Une zone de recherche, si le site dispose d’une recherche
• Le même en-tête et la même navigation que le reste du site

Lorsque votre configuration le permet, renvoyez un vrai statut 404 pour les pages qui n’existent pas. Un message « introuvable » renvoyé avec le statut 200 est ce que les moteurs de recherche appellent une soft 404 ; il peut gaspiller leur temps d’exploration et perturber l’indexation.

Erreurs courantes

• Tester uniquement en cliquant. Testez toujours en collant des URL profondes dans un nouvel onglet et en rafraîchissant.
• Un repli qui attrape tout. Les ressources et les routes d’API renvoient index.html, ce qui provoque des pages blanches et des erreurs d’API déroutantes.
• Une casse incohérente qui ne casse que sur le serveur.
• Déployer le dossier source au lieu du résultat du build.
• Restructurer les URL sans redirections. Chaque ancien lien devient un 404.

Les 404 dans Mythex

Dans Mythex, vous publiez depuis l’espace de travail, et les interfaces statiques sont déployées comme sites statiques. Si une page publiée renvoie 404, donnez à l’agent l’URL exacte, précisez si cela arrive au rafraîchissement ou au clic, ce que montre l’onglet Réseau, et demandez-lui de vérifier le routage. Publiez à nouveau après la correction, car l’application en ligne est un instantané jusqu’à ce que vous republiez. Si vous avez récemment modifié le projet et que le site en ligne semble ancien, publiez à nouveau et forcez le rechargement. Utilisez Corriger avec l’IA dans la boîte de dialogue de publication si le build échoue. Voir Comment publier et Dépannage de la publication dans la documentation, ainsi que notre guide sur le débogage d’une application créée par IA.

Liste de contrôle des 404

• Noté exactement quelles URL renvoient 404, et si cela arrive au clic, au rafraîchissement ou aux deux
• Le repli SPA sert index.html pour les routes de l’application, avec le statut 200
• Le repli exclut les vrais fichiers et /api/*
• Le routeur dispose d’une route de repli « introuvable »
• Le dossier du résultat du build est celui qui est publié, et le build a réussi
• Le chemin de base correspond à l’endroit où l’application est servie
• La casse des noms de fichiers correspond à chaque référence
• Les chemins des ressources commencent par /
• Le style de barre oblique finale est cohérent
• Les routes d’API sont déployées et routées en production
• Redirections 301 pour les anciennes URL
• Pages profondes testées en les collant dans un nouvel onglet

Questions