Cloud

Cloudflare Pages, Node 22 et pourquoi les déploiements simples gagnent

Une approche pratique pour garder un site technique statique simple sur Cloudflare Pages, avec un runtime Node explicitement figé et des déploiements pilotés par Git.

14 avr. 2026 cloudflarepagesnodedeployment

Pour un site de contenu technique, le moyen le plus rapide de perdre du temps consiste souvent à choisir un modèle de déploiement plus ambitieux que le projet lui-même.

Si l’objectif est une plateforme légère en Markdown ou MDX, avec des builds prévisibles et très peu d’exploitation, un site statique sur Cloudflare Pages reste une bonne option. La nuance compte néanmoins. La documentation Astro récente met fortement en avant Workers pour les scénarios full stack et le rendu à la demande, tandis que la documentation Cloudflare Pages continue de supporter les déploiements statiques classiques connectés à Git et référence explicitement Astro avec npm run build comme commande de build et dist comme répertoire de sortie. En d’autres termes, Pages reste pertinent tant que le site reste volontairement simple et statique.

Garder une architecture volontairement simple

Les sites techniques les plus fiables sont souvent les moins “magiques” :

  • les sources sont dans Git
  • le contenu est en MDX
  • la sortie est en HTML statique
  • le déploiement est déclenché par un push sur main
  • il n’y a ni base de données ni état applicatif ni chaîne de build fragile

Cette approche rend les incidents plus lisibles. Quand un build casse, le problème vient en général d’un nombre réduit de causes : dépendances manquantes, mauvais paramètres de build, mauvaise structure du dépôt ou asset jamais commité.

Pour un site Astro orienté statique, une configuration explicite comme celle-ci garde l’intention claire :

javascript astro.config.mjs 
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
integrations: [mdx()],
output: 'static'
});

Le déploiement piloté par Git n’est pas un détail

Pour un site éditorial, l’intégration Git est l’un des vrais avantages opérationnels de Pages.

Un push vers la branche de production doit suffire à déclencher un nouveau déploiement. Cela garde le modèle de livraison simple et traçable :

bash 
git add .
git commit -m "Publier un nouvel article"
git push origin main

Cette discipline devient encore plus utile quand le site commence à contenir du vrai contenu. Les changements de design, les ajouts d’articles et les ajustements d’infrastructure restent alors dans la même histoire versionnée.

Figer la version Node explicitement

Un détail souvent sous-estimé sur Cloudflare Pages concerne la gestion du runtime.

L’image de build v3 de Cloudflare utilise actuellement Node.js 22 par défaut, et permet des surcharges via NODE_VERSION, .nvmrc ou .node-version. En parallèle, le système v3 ne détecte pas la version Node depuis package.json engines. Si ton build dépend d’une version précise, il faut la fixer explicitement au lieu de supposer que engines sera respecté.

Un petit fichier à la racine suffit souvent :

text .node-version 
22.12.0

Ce choix évite une grande partie des cas “ça marche en local, mais pas en CI”.

Les premiers points à vérifier quand ça casse

Quand un site Astro statique échoue sur Pages, commence par les vérifications les plus simples :

  1. L’application est-elle bien à l’endroit où Pages pense la trouver ?
  2. Le build produit-il réellement dist/ ?
  3. Le changement a-t-il bien été poussé ?
  4. L’asset référencé par la page est-il bien commité dans public/ ?

Exécute localement la même commande que Pages :

bash 
npm run build

Si la sortie n’arrive pas dans dist, il faut régler ça avant toute autre chose.

Cas d’usage : plateforme éditoriale technique légère

Pour un site personnel ou une petite plateforme technique, le besoin est souvent simple :

  • frontend statique rapide
  • déploiement peu coûteux en temps
  • très peu de maintenance
  • architecture qu’on n’a pas besoin de surveiller en permanence

Cloudflare Pages avec Astro correspond encore bien à ce besoin. L’erreur n’est généralement pas de choisir Pages. L’erreur consiste plutôt à ajouter de la complexité avant qu’elle ne soit nécessaire.

Références