Diagnostiquer le cache Next.js sur Vercel

Publié le

14 juil. 2026

« Le cache est obsolete » peut decrire plusieurs problemes : un ancien deploiement, une reponse HTTP publique mise en cache, un fetch Next.js tague, une image optimisee ou des donnees qui n'ont jamais ete mises en cache. La correction la plus rapide et la plus sure consiste a classer le probleme avant de lancer une purge.

Etape 1 : reproduire une URL avec une valeur attendue connue

Choisissez une URL publique et notez ce qui devrait etre renvoye : une revision de deploiement, un prix produit, une date de mise a jour de contenu ou un checksum. Demandez-la deux fois sans modifier les en-tetes de requete :

curl -sS -I https://www.example.com/products/running-shoe
curl -sS https://www.example.com/products/running-shoe | shasum -a 256

Repetez les controles apres une courte pause. Conservez l'URL, l'horodatage, le statut, les en-tetes pertinents et le marqueur du corps. Un statut de cache seul ne prouve pas que le contenu est a jour.

Si votre projet est lie a Vercel, sa CLI peut aussi inspecter un chemin de deploiement de production ou protege :

vercel httpstat /products/running-shoe

vercel httpstat exige la CLI Vercel et l'outil httpstat. Il est utile pour le timing et les deploiements proteges, mais ne remplace pas une verification du corps de reponse.

Etape 2 : identifier la couche pouvant etre obsolete

Utilisez ce tableau avant toute invalidation :

x-vercel-cache decrit l'etat de reponse du CDN Vercel. Les valeurs courantes incluent HIT, MISS, STALE, REVALIDATED et BYPASS. Sur une route dynamique, l'en-tete peut etre MISS alors qu'un fetch de donnees Next.js a ete servi depuis un cache d'execution. Utilisez les logs applicatifs ou un marqueur de version intentionnel pour prouver le resultat de la couche donnees.

Etape 3 : inspecter le deploiement actif et les en-tetes de cache

Trouvez le deploiement qui sert le trafic, puis comparez son commit Git et sa configuration d'environnement avec la release attendue :

vercel inspect https://www.example.com

Pour un Route Handler public, inspectez les en-tetes sans suivre par erreur une redirection vers une URL differente :

curl -sS -I https://www.example.com/api/public-catalog

Verifiez :

• x-vercel-cache pour comprendre le resultat CDN ;
• Cache-Control, CDN-Cache-Control ou Vercel-CDN-Cache-Control lorsque votre route les definit ;
• les valeurs Set-Cookie, Authorization ou Vary qui rendent une politique partagee non sure ou fragmentent le cache ; et
• une redirection, reponse d'erreur, type de contenu ou revision de deploiement inattendus.

Vercel consomme certaines directives de cache partage avant de transmettre les en-tetes aux navigateurs. Ne concluez pas que le CDN a ignore une politique uniquement parce que la valeur Cache-Control visible par le navigateur differe de la source du Route Handler.

Etape 4 : verifier le contrat de cache applicatif

Examinez le fetch exact qui fournit la valeur obsolete. Pour des donnees publiques, il doit avoir une politique deliberee et un tag stable :

const response = await fetch("https://api.example.com/products", {
  next: {
    revalidate: 3600,
    tags: ["products"],
  },
})

Pour des donnees privees ou en temps reel, le diagnostic le plus sur est generalement une requete explicitement non cacheable :

const response = await fetch("https://api.example.com/account", {
  cache: "no-store",
  headers: { Authorization: `Bearer ${accessToken}` },
})

Ne « corrigez » pas une reponse privee obsolete en augmentant un TTL partage ou en ajoutant un identifiant utilisateur a une cle de cache. Retirez l'eligibilite au cache partage non sure et examinez plutot le comportement de session ou d'origine.

Etape 5 : utiliser la reprise la plus etroite

Choisissez l'action correspondant a la couche identifiee :

1. Mauvais deploiement : restaurez ou promouvez un deploiement connu comme bon, puis verifiez le corps de reponse.

2. Donnees publiques taguees : declenchez le workflow authentifie revalidateTag de l'application pour le tag et la route connus.

3. Cache de donnees Vercel : apres confirmation du tag et de l'impact, utilisez la commande CLI du projet lie :

   vercel cache invalidate --tag products
   

4. Reponse CDN publique : corrigez d'abord le deploiement ou les en-tetes de cache. Utilisez une purge CDN uniquement via le workflow operationnel examine et seulement pour le perimetre public concerne.

5. Image optimisee : invalidez l'image source specifique plutot que de purger du contenu non lie.

Les commandes de cache Vercel sont des outils operationnels, non un substitut a la correction d'une mauvaise cle de cache, d'un en-tete non sur ou d'un enregistrement source errone. Une purge large peut produire un thundering herd sur l'origine et ne pas corriger la cause racine.

Etape 6 : inspecter les logs et prouver la reprise

Recherchez les logs de production autour du moment du deploiement et de l'invalidation :

vercel logs --environment production --query "cache" --since 1h --expand

Recherchez les echecs de revalidation, les timeouts amont, les incoherences de tags et la revision de deploiement ayant traite la requete. Repetez ensuite les memes controles d'en-tete et de corps que dans l'etape 1. Consignez la commande de reprise, son perimetre, l'operateur et le resultat dans l'incident ou l'enregistrement de changement.

Etape 7 : prevenir le prochain incident

Transformez le diagnostic reussi en petit runbook :

• Attribuez un responsable, une cible de fraicheur et une URL de test sure a chaque route cacheable.
• Emettez une revision de deploiement ou de contenu non sensible dans les reponses de test publiques.
• Conservez une correspondance entre les tags de donnees et les chemins rendus.
• Alertez sur les echecs de webhooks et les erreurs de revalidation repetees.
• Testez un chemin authentifie chaque fois qu'une regle de cache ou un en-tete de reponse change.
• Examinez le comportement de cache depuis plusieurs regions representatives pour les routes a fort trafic.

References faisant autorite

• Vercel : diagnostiquer les problemes de cache
• Vercel CDN Cache
• En-tetes de reponse Vercel
• Next.js revalidateTag