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

Si votre application fonctionne en local mais que des pages renvoient une 404 après le déploiement, la cause la plus fréquente est l'absence de routage d'application à page unique (SPA) : le serveur cherche un fichier nommé /dashboard qui n'existe pas, car cette route n'existe que dans le JavaScript. La solution consiste à ajouter 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 une 404 et comment vous y êtes arrivé. Le schéma indique directement la cause.

Étape 1 : Identifier le schéma

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

Étape 2 : Ajouter le fallback SPA

C'est le cas classique. Dans une application à page unique React, Vue ou Svelte, le serveur ne dispose que de quelques vrais fichiers : index.html et quelques fichiers JavaScript et CSS. Des 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 quoi que ce soit au serveur.
• Actualiser la page ou ouvrir un lien directement échoue : le navigateur demande /dashboard au serveur, qui n'a aucun fichier de ce nom, et renvoie une 404.

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

Assurez-vous que la règle n'avale pas les vrais fichiers : les requêtes pour /assets/app.js doivent toujours renvoyer le fichier JavaScript. Si elles renvoient index.html à la place, vous obtenez une page blanche avec l'erreur « Failed to load module script ». Voir comment 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 plutôt que rien.

Si vous ne pouvez pas modifier les réglages du serveur, le routage par hash (URL du type /#/dashboard) contourne 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 esthétiques et moins bien comprises 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 généralement de vrais fichiers ou de routes serveur pour chaque page, donc ce problème est moins fréquent avec eux. Leur équivalent est une page qui n'a pas été générée au moment du build.

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

Si tout renvoie une 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 de 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 peut n'avoir 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 (option base de Vite, basename de React Router), sinon chaque route et chaque ressource manquera.

Étape 4 : Corriger les fichiers manquants et les chemins incorrects

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

• Sensibilité à la casse. macOS et Windows traitent généralement 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 du dossier 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 placé ailleurs dans le projet peut ne jamais être déployé.
• Chemins relatifs. images/photo.jpg est résolu par rapport à l'URL courante, donc il casse sur /blog/post-1. Utilisez /images/photo.jpg.
• Fichiers téléversés enregistrés sur le disque local. Si les fichiers des utilisateurs ont été écrits dans le dossier du serveur, ils disparaissent au 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 ajoutent ou retirent la barre oblique de façon différente, 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 celle-ci. C'est aussi bénéfique pour les moteurs de recherche, qui sinon peuvent voir deux copies de chaque page.

Étape 6 : Corriger les routes d'API qui renvoient une 404

Si la page se charge mais que l'onglet Réseau montre des requêtes /api/... qui renvoient une 404 :

• Le backend n'est pas déployé. Un hébergeur statique ne sert que des fichiers ; un backend 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 frontend doit appeler la véritable adresse de l'API.
• Le fallback SPA a tout intercepté. Une requête d'API qui renvoie index.html avec le statut 200 signifie que la règle de repli est trop large. Excluez /api/* de celle-ci.

L'application publiée renvoie une 404 sur les requêtes vers /api/orders, mais elles fonctionnent dans l'aperçu. Vérifie comment /api est routé dans l'aperçu et dans l'application publiée, et fais en sorte que le frontend publié atteigne le backend de la même manière.

Étape 7 : Rediriger les anciennes URL

Si vous avez changé de site ou restructuré le vôtre, les anciennes URL encore utilisées par les internautes et les moteurs de recherche renverront une 404. Ajoutez une redirection 301 (permanente) de chaque ancienne URL vers sa nouvelle adresse. Tenez une liste et testez un échantillon après la mise en ligne. Notre guide sur la migration d'un site WordPress explique comment constituer cette liste.

Étape 8 : Vérifier le domaine

Si l'application fonctionne à l'adresse de l'hébergeur mais renvoie une 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 de l'hébergeur. Voir comment connecter un domaine personnalisé.

Rendre votre vraie page 404 utile

Certaines 404 sont légitimes : quelqu'un a mal saisi 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, qui 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 actualisant.
• Un fallback qui intercepte 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 se manifeste 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 une 404.

Les 404 dans Mythex

Dans Mythex, vous publiez depuis l'espace de travail, et les frontends statiques se déploient comme des sites statiques. Si une page publiée renvoie une 404, donnez à l'agent l'URL exacte, indiquez si cela se produit à l'actualisation ou au clic, et ce que montre l'onglet Réseau, puis demandez-lui de vérifier le routage. Republiez après la correction, car l'application en ligne reste un instantané tant que vous ne republiez pas. Si vous avez récemment modifié le projet et que le site en ligne semble ancien, republiez 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 avec l'IA.

Checklist des 404

• Noté exactement les URL qui renvoient une 404, et si c'est au clic, à l'actualisation, ou aux deux
• Le fallback SPA renvoie index.html pour les routes de l'application, avec le statut 200
• Le fallback exclut les vrais fichiers et /api/*
• Le routeur a 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 des barres obliques finales est cohérent
• Les routes d'API sont déployées et routées en production
• Des redirections 301 existent pour les anciennes URL
• Les liens profonds ont été testés en les collant dans un nouvel onglet

Questions