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/chunksne 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.
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
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
| Option | Ce qu’elle règle | Limite |
|---|---|---|
Invalidation /* en fin de pipeline | Tous les cas | Une étape de plus dans le pipeline |
Réduire le s-maxage | Raccourcit la fenêtre | Le HTML reste périmé pendant la durée restante |
| Garder les anciens assets servables quelques heures | Le HTML périmé fonctionne encore | Deux 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-maxageplusstale-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.