Kamorion

Blog · AWS · · 6 min de lecture

Next.js derrière CloudFront : sans invalidation, chaque déploiement casse le site

Après un déploiement Next.js, le site s’affiche sans style pendant un temps, puis revient tout seul. Le HTML mis en cache par CloudFront pointe vers des fichiers du build précédent, qui n’existent plus.

Le scénario est toujours le même. Un déploiement Next.js se termine sans erreur. Quelques minutes plus tard, on signale que le site « s’affiche mal » : plus de CSS, une partie du JavaScript absente, des pages à moitié interactives. Puis, sans que personne n’intervienne, tout revient dans l’ordre.

Nous avons rencontré ce cas sur un site e-commerce déployé chaque jour. Chaque matin, après le déploiement, le site restait cassé pendant environ deux heures. L’application n’avait rien de faux. Le problème venait du cache.

Ce que l’on observe

Côté origine, les journaux montrent des requêtes vers /_next/static/chunks/<hash>.js ou .css qui échouent : un 404, ou un 302 si un middleware de langue intercepte le chemin. Pourtant, le pod est parfaitement cohérent avec lui-même. Le HTML qu’il produit référence bien les fichiers qu’il contient.

Deux indices orientent vite le diagnostic :

  • sur un chargement fautif, aucune requête HTML n’atteint l’origine, seules les requêtes d’assets y arrivent ;
  • dans le pod, la liste de .next/static/chunks ne contient pas les noms demandés.

Autrement dit, le HTML servi au navigateur ne vient pas du pod. Il vient du cache CloudFront.

Le mécanisme

Next.js nomme ses fichiers statiques d’après leur contenu. À chaque build, les fichiers qui ont changé reçoivent un nouveau nom, et les anciens disparaissent de l’image déployée.

De son côté, une page rendue côté serveur pour un visiteur anonyme peut porter un en-tête comme celui-ci :

Cache-Control: public, s-maxage=3600, stale-while-revalidate=3600

CloudFront garde alors ce HTML une heure, puis peut encore le servir périmé pendant une heure supplémentaire, le temps de le revalider. Au total, une page peut rester en cache jusqu’à deux heures. C’est exactement la durée de panne que nous observions.

Avant le déploiementCloudFront garde le HTML de la version N
Déploiementles pods passent en version N+1, les anciens fichiers disparaissent
Visiteurreçoit le HTML N depuis le cache
Navigateurdemande les fichiers de la version N, l’origine répond 404
Fin de la fenêtrele HTML expire, CloudFront redemande la page, tout revient
Le HTML en cache survit au build qu’il décrit.

Rappel utile : derrière CloudFront, la durée réelle de cache dépend aussi du behavior. Le DefaultTTL ne s’applique que si l’origine n’envoie aucun Cache-Control, et le MaxTTL plafonne le s-maxage de l’origine. Un behavior réglé pour respecter les en-têtes de l’application, avec un MaxTTL élevé, laisse donc passer un s-maxage d’une heure tel quel.

Les réglages qui aggravent la panne

Le mécanisme de base suffit à casser le site. Trois réglages courants l’aggravent ou la prolongent.

Un reverse proxy qui pose un cache long sur tous les .js et .css. Une règle du type « tout fichier .js est cacheable un an » s’applique aussi aux réponses en erreur. CloudFront met alors en cache le 404 ou le 302 de l’asset manquant. Il faut conditionner l’en-tête au statut de la réponse, par exemple avec Apache :

Header set Cache-Control "public, max-age=31536000, immutable" "expr=%{REQUEST_STATUS} == 200"

Un middleware de langue qui redirige tout chemin sans préfixe. Un asset manquant devient un 302 vers /fr/_next/... au lieu d’un 404 franc. L’erreur est masquée, et la redirection peut à son tour être mise en cache. Le chemin /_next/ doit être exclu de ce routage.

Un MaxTTL de plusieurs jours. Le HTML expire selon son s-maxage, mais une erreur mise en cache avec un en-tête trop généreux peut survivre bien plus longtemps que la fenêtre de déploiement.

Réglage piégeux

Cache-Control long sur tout .js et .css, quel que soit le statut

Middleware de langue appliqué à /_next/

Aucune action CloudFront après le déploiement

Réglage sain

Cache-Control long seulement sur les réponses 200

/_next/ exclu, un asset absent renvoie un 404 franc

Invalidation /* en fin de pipeline

Le cache long est fait pour les fichiers versionnés qui existent, pas pour leurs erreurs.

La correction : invalider en fin de déploiement

La seule mesure qui couvre tous les cas est une invalidation CloudFront de /* à la fin du job de déploiement. Elle est peu coûteuse : les 1 000 premiers chemins invalidés chaque mois sont gratuits, et un chemin avec joker comme /* compte pour un seul.

L’ordre compte. L’invalidation doit partir une fois le déploiement terminé, quand plus aucun pod de l’ancienne version ne répond. Sinon, CloudFront peut redemander une page à un ancien pod et remettre en cache le HTML périmé. Sur Kubernetes, cela donne par exemple :

kubectl rollout status deployment/<application> -n <namespace> --timeout=10m

INVALIDATION_ID=$(aws cloudfront create-invalidation \
  --distribution-id "$DISTRIBUTION_ID" --paths "/*" \
  --query 'Invalidation.Id' --output text)

aws cloudfront wait invalidation-completed \
  --distribution-id "$DISTRIBUTION_ID" --id "$INVALIDATION_ID"

L’attente finale n’est pas obligatoire, mais elle rend le job honnête : quand il passe au vert, le cache est vraiment propre. Le rôle du pipeline n’a besoin que de cloudfront:CreateInvalidation et cloudfront:GetInvalidation sur la distribution concernée.

Les alternatives, et leurs limites

OptionCe qu’elle règleLimite
Invalidation /* en fin de pipelineTous les casUne étape de plus dans le pipeline
Réduire le s-maxageRaccourcit la fenêtreLe HTML reste périmé pendant la durée restante
Garder les anciens assets servables quelques heuresLe HTML périmé fonctionne encoreDeux versions côte à côte, plus lourd à opérer

Réduire le s-maxage dégrade aussi l’intérêt du cache pour tout le reste de la journée, pour un problème qui ne survient qu’au déploiement. Conserver les anciens assets est la solution la plus robuste en théorie, mais elle demande un stockage partagé des fichiers statiques et une politique de nettoyage. C’est rarement justifié quand une invalidation suffit.

Vérifier en deux commandes

Pour savoir si une page vient du cache, et depuis combien de temps :

curl -sSD - -o /dev/null https://www.exemple.fr/ | grep -iE 'cache-control|x-cache|age'

Un x-cache: Hit from cloudfront avec un age supérieur au temps écoulé depuis le déploiement confirme le diagnostic : le HTML servi date de l’ancienne version. Juste après l’invalidation, la même commande doit renvoyer un Miss, puis un Hit avec un age faible.

Ce type de piège tient à la clé et à la durée de cache, comme pour les tests A/B côté serveur derrière un CDN. Le cache accélère le site tant qu’il décrit la version en ligne. Dès qu’il lui survit, il le casse.

À retenir

  • Un HTML en cache référence des fichiers. Si le déploiement les supprime, le cache doit suivre.
  • La durée de la panne se lit dans l’en-tête : s-maxage plus stale-while-revalidate.
  • Une invalidation /* après la fin du rollout règle le problème pour un coût négligeable.
  • Les erreurs sur les assets ne doivent jamais recevoir un cache long.

Nous intégrons ce type de garde-fou dans nos missions d’exploitation AWS et de pipelines CI/CD. Votre site se dégrade après chaque mise en production ? Parlons-en.

Contact

Commençons par un audit

Nous lisons votre plateforme : ce qui est en code et ce qui ne l’est pas, ce qui vous expose, ce qui vous coûte, et ce que nous ferions en premier.

  • Premier échange sans engagement
  • Un diagnostic écrit, qui reste à vous
  • Accès en lecture seule pendant l’audit

Ou écrivez-nous : [email protected]