Diagnostiquer une API qui fonctionne sur localhost mais échoue en production

Une requête qui fonctionne sur votre ordinateur ne prouve pas qu’elle fonctionnera depuis le site publié. En local, le frontend et l’API peuvent partager une origine, un proxy Vite peut réécrire le chemin ou le navigateur peut utiliser une URL qui n’existe que sur votre machine. En production, le domaine, le protocole, les routes et la politique du navigateur changent. Commencez par identifier la requête réellement envoyée et la réponse reçue.

Ce guide diagnostique la frontière entre frontend et API. Il n’explique ni la construction ni la publication d’une application React, ni la configuration des variables publiques Vite : consultez le guide de déploiement React et Vite depuis Git et la documentation des variables Vite. Pour choisir où exécuter chaque composant, lisez de quel hébergement une application créée avec l’IA a besoin.

1. Examinez la requête dans Network

Ouvrez les outils de développement, sélectionnez Network/Réseau, reproduisez une action puis sélectionnez la requête en échec. Notez son URL complète, sa méthode, son statut, son Content-Type, son initiateur et la présence éventuelle d’une requête OPTIONS préalable. Ne partagez ni cookies, ni en-têtes d’autorisation, ni corps contenant des données personnelles, ni clés.

Vérifiez le nom d’hôte. S’il contient localhost, 127.0.0.1 ou une adresse privée, le navigateur du visiteur tente de joindre son propre appareil ou réseau, pas votre ordinateur ni votre serveur. Remplacez cette adresse par une route d’API accessible depuis le site ou par un véritable domaine HTTPS que vous contrôlez. Recherchez aussi ces valeurs dans les fichiers construits : une variable appelée « production » ne modifie pas une valeur déjà intégrée si vous ne reconstruisez pas l’application.

Un chemin tel que /api/orders est demandé à la même origine que celle de la page. Il ne fonctionne que si la plateforme, le serveur web ou un proxy de production transmet ce chemin à votre API. server.proxy de Vite peut aider avec npm run dev, mais cette configuration n’est pas intégrée aux fichiers statiques créés par npm run build. Le navigateur ne peut pas créer un service backend.

2. Distinguez le preflight de la requête réelle

Pour un appel entre origines qui utilise JSON, Authorization ou d’autres en-têtes non simples, le navigateur envoie souvent d’abord OPTIONS. Le serveur doit répondre avec l’origine, les méthodes et les en-têtes autorisés. Si le preflight est refusé, le navigateur n’envoie pas la requête principale qui suit.

C’est différent d’une requête simple, par exemple certains POST avec Content-Type: text/plain. Le serveur peut la recevoir et modifier son état même si CORS empêche JavaScript d’en lire la réponse. CORS détermine quelles réponses le navigateur peut lire ; il n’authentifie pas l’utilisateur et ne garantit pas que le serveur n’a pas traité l’écriture. N’utilisez pas Access-Control-Allow-Origin: * comme correctif ou contrôle d’accès. Authentifiez et autorisez côté backend, validez le corps et appliquez une protection CSRF si nécessaire. Vérifiez Origin selon votre conception ; cet en-tête seul n’est pas non plus une authentification.

3. Un statut HTTP 200 peut contenir la mauvaise page

Examinez le type et le corps de la réponse. Si /api/profile renvoie 200 et text/html avec le squelette de votre application, une règle de repli a probablement envoyé la page d’accueil à la place de la réponse API. Le transport a réussi, mais votre code attendait du JSON. Un 404, 502 ou une page d’erreur HTML sur la route API constitue un autre indice.

Ne considérez pas l’opération comme enregistrée simplement parce que fetch() n’a pas levé d’exception : les statuts HTTP d’erreur fournissent normalement quand même une réponse. Vérifiez response.ok et le type de contenu avant de traiter la réponse. Exemple :

const response = await fetch('/api/status');
const type = response.headers.get('content-type') || '';
if (!response.ok || !type.includes('application/json')) {
  throw new Error(`Réponse inattendue : HTTP ${response.status}`);
}
const data = await response.json();

Cela vérifie seulement le statut HTTP, le type MIME et la possibilité d’analyser le corps en JSON ; les champs ne sont pas validés. Vérifiez la structure de l’objet et le résultat de l’opération avant d’annoncer un enregistrement. Cela ne corrige pas le routage et ne crée pas d’API.

4. Reproduisez le problème par étapes

Essayez l’URL exacte du backend en dehors du navigateur avec un client HTTP et des données synthétiques. Si l’échec persiste, vérifiez DNS, TLS, chemin, processus, méthode et journaux backend. Si le client HTTP réussit mais Chrome échoue, examinez preflight, origine et en-têtes. Si Chrome affiche 200 avec un corps HTML, corrigez le routage du serveur ou la règle de repli. Recommencez ensuite avec une opération de lecture seule ; évitez les écritures sur des données réelles.

Côté backend, confirmez si la requête est arrivée et si elle a produit un effet. Un message « blocked by CORS » dans la console du navigateur ne prouve pas qu’aucune écriture n’a eu lieu. Utilisez des identifiants de requête et des journaux sans secrets pour corréler le résultat.

Ce qui a été testé et ce qui ne l’a pas été

L’expérience locale de cet article a exécuté dix cas avec HTTP et Chrome sur un fixture synthétique : proxy de développement, absence de proxy dans un build statique, repli HTML en statut 200, route de même origine, preflight autorisé ou refusé, écriture simple dont le résultat est masqué par CORS, gardes d’écriture indépendantes, cycle de vie du processus et routes/assets à deux tailles de fenêtre. Tous ont réussi sur ce fixture. Le test a aussi vérifié qu’un Origin falsifié pouvait écrire dans la démonstration protégée par origine, confirmant que ce contrôle n’est pas une authentification.

Le fixture n’est pas une intégration au produit Hostbrid ni à un compte client. Il ne teste ni authentification, cookies, paiements, base de données, courrier, TLS, persistance ou déploiements clients. La démo CORS-only autorise volontairement une écriture synthétique et ne doit pas être copiée en production. Le test ne prouve pas non plus l’indexation ou le classement.

Pour une application qui nécessite un processus actif, vérifiez la disponibilité et les limites de Projects. Si vous avez besoin de contrôler le système d’exploitation et de l’administrer vous-même, consultez VPS. Choisissez selon le processus réellement requis par votre backend et confirmez le périmètre et le prix du forfait avant commande.