Guide complet Cloudflare Pages pour blogs statiques : configurer 5 frameworks sans piège

Premier article de blog terminé, clic sur « Déployer ». Trois minutes plus tard, Cloudflare Pages affiche « Déploiement réussi ». Copie du lien dans le navigateur — page blanche, console F12 pleine de 404.

Le choc du premier déploiement Astro : réponses Google contradictoires, trois ou quatre heures perdues, et la cause finale — répertoire de sortie public au lieu de dist (valeur par défaut Astro).

90 % des échecs viennent de deux réglages mal compris : commande de build et répertoire de sortie. Cet article donne la config exacte pour Astro, Hugo, Hexo, Gatsby et Eleventy sur Cloudflare Pages, plus un diagnostic rapide en cas de page blanche ou d’échec de build. Suivez le guide : du dépôt Git à la mise en ligne en 10 minutes.

Pourquoi Cloudflare Pages ? (en tenant compte des changements 2025)

Pourquoi je recommande Cloudflare Pages pour un blog statique.

Gratuit, et vraiment rapide. Cloudflare dispose de plus de 300 datacenters dans le monde. Votre blog est distribué automatiquement — accès rapide partout. J’ai utilisé GitHub Pages et Vercel ; Cloudflare Pages est plus stable, surtout depuis la Chine. Gratuit, sans limite de trafic ni de builds.

Déploiement automatique depuis Git, très pratique. Connectez GitHub ou GitLab : chaque git push déclenche build et déploiement. Chaque Pull Request obtient un lien de preview — idéal pour valider avant merge. Très utile en équipe.

Certificat SSL gratuit et domaine personnalisé. Pas de galère de certificat ; liaison de domaine simple, DNS actif en quelques minutes.

Un point à connaître : en avril 2025, Cloudflare a recentré sa stratégie sur Workers ; Pages est en mode « maintenance », sans grosses évolutions.

Pour un blog statique, l’impact est limité. Pages reste stable et suffisant. Blog ou doc sans SSR complexe : Pages reste le meilleur choix. Workers convient aux projets dynamiques, API ou edge computing avancé.

En bref : blog purement statique → Pages sans hésitation. Fonctionnalités serveur plus tard → migration Workers à ce moment-là.

Configuration standard des 5 frameworks (chapitre central)

Voici la config exacte pour les 5 générateurs de sites statiques les plus courants. Remplissez directement.

Tableau de configuration rapide

Gardez ce tableau — chaque config a été vérifiée. Détail par framework ci-dessous.

Configuration Astro

Astro est mon framework préféré pour les blogs statiques : performant et agréable à utiliser.

Configuration standard :

• Commande de build : npm run build ou astro build
• Répertoire de sortie : dist

Site purement statique (SSG) : config par défaut suffit. Pour le rendu côté serveur (SSR), installez l’adaptateur @astrojs/cloudflare et ajoutez dans astro.config.mjs :

import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'server',
  adapter: cloudflare()
};

Pour un répertoire de sortie personnalisé (ex. build) :

export default {
  outDir: 'build'
};

Je conseille de garder dist par défaut — moins de confusion en collaboration.

Configuration Hugo (la plus piégeuse)

Hugo accumule le plus de pièges. Mon premier déploiement Hugo m’a pris une soirée entière.

Configuration standard :

• Commande de build : hugo ou hugo -b $CF_PAGES_URL
• Répertoire de sortie : public
• Variable d’environnement (obligatoire) : HUGO_VERSION = 0.143.1

Cloudflare Pages utilise Hugo 0.54 par défaut — version de 2019 ! La plupart des thèmes exigent 0.80+, voire 0.120+. Sans HUGO_VERSION, échec garanti.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Configuration des variables : section « Flux pratique » plus bas. En résumé : Settings > Environment variables :

• Nom : HUGO_VERSION
• Valeur : 0.143.1 (précision exacte, pas 0.143)

Détail baseURL : avec le domaine .pages.dev Cloudflare (sans domaine perso), utilisez :

hugo -b $CF_PAGES_URL

$CF_PAGES_URL est fourni automatiquement — liens internes, RSS, sitemap fonctionnent correctement.

Configuration Hexo

Hexo est un framework éprouvé, config relativement simple.

Configuration standard :

• Commande de build : hexo generate (raccourci hexo g)
• Répertoire de sortie : public

Peu de problèmes en général. Certains thèmes ou plugins imposent une version Node.js. En cas d’échec, définissez NODE_VERSION :

• Nom : NODE_VERSION
• Valeur : 14.3 ou 18.17.0 (selon votre version locale)

Vérifiez avec node -v en local, puis alignez sur Cloudflare Pages.

Configuration Gatsby

Gatsby est le plus simple — rarement de souci.

Configuration standard :

• Commande de build : gatsby build
• Répertoire de sortie : public

C’est tout. J’ai déployé plusieurs blogs Gatsby pour des amis, sans incident.

Configuration Eleventy

Eleventy (11ty) est un générateur léger, config simple aussi.

Configuration standard :

• Commande de build : npx @11ty/eleventy
• Répertoire de sortie : _site (underscore au début)

Attention : _site, pas site. Une faute de frappe et les fichiers sont introuvables.

Pour personnaliser le répertoire de sortie, créez .eleventy.js à la racine :

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Configuration Next.js (changement 2025)

Blog Next.js : un changement important en 2025.

Configuration standard (nouvelle approche 2025) :

• Commande de build : npx opennextjs-cloudflare
• Répertoire de sortie : .worker-next

Important : le paquet @cloudflare/next-on-pages est obsolète. Cloudflare recommande @opennextjs/cloudflare.

Tutoriels mentionnant next-on-pages : ignorez-les. Nouvelle approche :

1. Installer : npm install @opennextjs/cloudflare
2. Build command : npx opennextjs-cloudflare
3. Répertoire de sortie : .worker-next

Pour un blog purement statique, je préfère Astro ou Hugo — plus léger. Next.js convient aux applications dynamiques.

Flux pratique : du dépôt Git à la mise en ligne

Config connue — déploiement pas à pas. Environ 10 minutes.

Préparation

Avant de commencer, trois vérifications :

1. Code poussé sur GitHub ou GitLab — dernière version visible sur le dépôt
2. package.json présent (projet Node.js) — dépendances listées, pas seulement installées en local
3. Vérifier .gitignore — node_modules, dist, public ignorés ; pas d’artefacts de build dans Git

J’ai vu quelqu’un pousser node_modules — conflits au déploiement. Vérifiez .gitignore.

Étapes de déploiement détaillées

Étape 1 : connexion Cloudflare, accès à Pages

Ouvrez dash.cloudflare.com, connectez-vous (inscription gratuite).

Menu gauche Workers & Pages, puis Create application.

Étape 2 : choisir « Connecter à Git »

Deux options :

• Connect to Git — déploiement auto GitHub/GitLab (c’est celle-ci)
• Direct Upload — upload manuel (déconseillé)

Connect to Git, puis GitHub ou GitLab.

Étape 3 : autorisation d’accès

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Première connexion : autoriser Cloudflare. Sign in → redirection GitHub/GitLab.

Permissions : « Only select repositories » pour limiter l’accès.

Étape 4 : sélectionner le dépôt

Trouvez votre projet blog. Absent ? Rafraîchissez ou réautorisez.

Étape 5 : réglages de build (crucial !)

• Project name : partie du domaine .pages.dev (ex. my-blog → my-blog.pages.dev)
• Production branch : main ou master
• Framework preset : votre framework ou None

Build settings — selon le tableau :

• Build command :

  • Astro : npm run build
  • Hugo : hugo ou hugo -b $CF_PAGES_URL
  • Hexo : hexo generate
  • Gatsby : gatsby build
  • Eleventy : npx @11ty/eleventy
  • Next.js : npx opennextjs-cloudflare

• Build output directory :

  • Astro : dist
  • Hugo : public
  • Hexo : public
  • Gatsby : public
  • Eleventy : _site
  • Next.js : .worker-next

Framework preset : valeurs préremplies, pas toujours correctes — vérifiez.

Étape 6 : variables d’environnement (si nécessaire)

Environment variables (advanced) → Add variable.

• Hugo (obligatoire) :

  • Variable name : HUGO_VERSION
  • Value : 0.143.1 (précision à trois chiffres)

• Hexo (si besoin) :

  • Variable name : NODE_VERSION
  • Value : 14.3 ou 18.17.0

Étape 7 : enregistrer et déployer

Vérifiez, puis Save and Deploy. Logs en temps réel — 1 à 3 minutes en général.

Étape 8 : vérifier le résultat

« Success! Your site is live! » + lien votre-projet.pages.dev. Cliquez — votre blog s’affiche.

Variables d’environnement en détail

Si non configurées au déploiement, ou à modifier plus tard :

1. Projet Cloudflare Pages
2. Onglet Settings
3. Environment variables
4. Add variable
5. Nom et valeur, Save

Variables courantes :

• HUGO_VERSION : version Hugo (ex. 0.143.1)
• NODE_VERSION : version Node.js (ex. 18.17.0)
• CF_PAGES_URL : fourni par Cloudflare, pour baseURL

Important : après modification, redéployer. Deployments → trois points → Retry deployment.

Déploiements de preview

Fonctionnalité très utile : chaque Pull Request génère un lien de preview.

PR sur GitHub → Cloudflare build le code et fournit une URL de preview. Validez avant merge.

Pratique en équipe pour la relecture de contenu.

Problèmes courants et diagnostic

Trois erreurs les plus fréquentes — couvrent ~95 % des cas.

Problème 1 : échec de build (Building Failed)

Symptômes : bloqué sur « Building », puis « Build failed », icône rouge.

Ne relancez pas tout de suite — consultez les logs.

Diagnostic :

1. Logs de build
   • View build log ou Deployment details
   • Messages rouges en bas — dernières lignes = cause probable
2. Commande de build
   • Settings > Build & deployments
   • Conforme au tableau ? Erreur fréquente : npm build au lieu de npm run build
3. Dépendances
   • « Cannot find module » ou « Command not found » → dépendance manquante dans package.json
   • Installé en local mais pas ajouté (npm install --save)
4. Version du framework
   • Hugo : 99 % sans HUGO_VERSION — log « Theme requires Hugo Extended version » → ajoutez HUGO_VERSION = 0.143.1
   • Hexo : version Node incompatible → NODE_VERSION = 18.17.0

Cas réel : déploiement Hugo d’un ami, log « Hugo version 0.54.0 does not support this theme ». Ajout de HUGO_VERSION = 0.120.0 → déploiement immédiat.

Problème 2 : page blanche (le plus fréquent)

Symptômes : déploiement réussi, site vide, 404 en console F12.

90 % des cas : mauvais répertoire de sortie.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Diagnostic :

1. F12
   • Console : erreurs ?
   • Network : ressources 404 ?
   • Sources : structure correcte ?
2. Répertoire de sortie (~90 % des cas)
   • Settings > Build & deployments
   • Build output directory correct ?
   • Erreurs courantes :
     • Astro : public au lieu de dist
     • Hugo : dist au lieu de public
     • Eleventy : site au lieu de _site
3. baseURL ou publicPath
   • Sous-chemin (ex. example.com/blog) → configurer baseURL
   • Hugo : hugo -b $CF_PAGES_URL
   • Astro : base: '/blog' dans astro.config.mjs
   • Vue/React : publicPath: './' possible
4. Mode de routage (SPA)
   • Vue Router ou React Router en mode history → 404 au rafraîchissement
   • Solutions :
     • Mode hash (URL avec #)
     • Fichier _redirects à la racine :

       /* /index.html 200

Cas réel : mon blog Astro, page blanche — répertoire public au lieu de dist. Parfois c’est aussi simple.

Problème 3 : styles ou ressources non chargés

Symptômes : contenu visible, styles cassés, images absentes.

Diagnostic :

1. Network (F12) — CSS, JS, images en 404 ? Chemins corrects ?
2. Chemins des ressources
   • /assets/style.css (absolu) + sous-chemin → introuvable
   • Solutions : mécanismes du framework
     • Astro : import des ressources
     • Hugo : .RelPermalink ou absURL
     • Hexo : url_for()
3. CDN externe
   • jsDelivr, cdnjs — lien accessible ?
   • Alternative : BootCDN

Cas réel : blog Hexo d’un ami, pas de styles. CSS à /css/style.css, fichiers à /blog/css/style.css. Sous-chemin non configuré dans _config.yml — ajout de root: /blog/, regénération, résolu.

Liste de vérification rapide

1. ✓ Logs de build — message d’erreur
2. ✓ Commande de build (tableau)
3. ✓ Répertoire de sortie (tableau)
4. ✓ Variables d’environnement (HUGO_VERSION pour Hugo)
5. ✓ F12 — console et réseau
6. ✓ .gitignore — pas d’artefacts dans Git
7. ✓ Build local (npm run build, hugo, etc.)

Toujours bloqué ? Forum Cloudflare ou documentation Troubleshooting.

Astuces avancées : un blog plus professionnel

Le blog est en ligne — ce n’est que le début. Quelques améliorations simples mais efficaces.

Domaine personnalisé

.pages.dev fonctionne, un domaine propre est plus professionnel. SSL gratuit inclus.

Étapes :

1. Acheter un domaine (GoDaddy, OVH, etc.)
2. Projet Pages → Custom domains
3. Set up a custom domain (ex. blog.example.com)
4. Enregistrements DNS fournis par Cloudflare → ajouter chez le registrar
5. Propagation DNS (minutes à heures)
6. HTTPS configuré automatiquement

Astuce : domaine géré par Cloudflare → DNS plus rapide, config auto.

Optimisation du build

Beaucoup d’articles → builds longs. Quelques pistes :

1. Cache — Pages met en cache node_modules par défaut
2. Moins de dépendances — supprimer les paquets inutiles ; CDN pour jQuery, etc.
3. Build parallèle — Hugo --gc ; Astro experimental.contentCollectionCache
4. Stratégie de branches — travail sur dev, merge vers main pour la prod

Monitoring et analytics

Données d’accès :

1. Projet Pages → Analytics
2. Requêtes, bande passante, pays, tendances

Web Vitals : vitesse de chargement, INP — utile pour optimiser (images, lazy loading).

Automatisation

GitHub Actions pour aller plus loin :

• Publication programmée — articles avec date future
• Sitemap auto — soumission aux moteurs après déploiement
• Compression d’images — avant push

Pas obligatoire, mais pratique. Templates communautaires disponibles.

Conclusion

Déployer un blog statique n’est pas si compliqué. Deux réglages clés : commande de build et répertoire de sortie. Tableau correct → 90 % des problèmes évités.

Récapitulatif :

Problème ? Consultez les logs, puis cette checklist. Dans la plupart des cas, c’est une config incorrecte.

Lancez-vous. Cloudflare Pages, dépôt Git, bonne config — blog en ligne en 10 minutes.

Si cet article vous a aidé, partagez-le. Question non couverte ? Commentaire bienvenu.

Bon déploiement et bonne écriture !