Échec de build CF Pages ? 8 problèmes courants et leurs solutions pour gagner une demi-journée de debug

Les logs de build Cloudflare Pages affichent « Failed » en rouge. Cinquième échec ce soir, démo client demain matin. Cinq cents lignes de logs, npm ERR! partout — par où commencer ? Les solutions trouvées en ligne n’ont pas toujours aidé, parfois empiré les choses.

La plupart des échecs CF Pages relèvent de trois catégories : différences d’environnement, configuration des dépendances, compatibilité de version. Maîtrisez ces schémas et 90 % des problèmes se résolvent en 10 minutes. Cet article décrit l’environnement de build Cloudflare Pages, 8 scénarios d’échec les plus courants (avec messages d’erreur réels et étapes complètes), plus des recommandations préventives. Vous aurez une méthode de diagnostic claire.

Partie 1 : comprendre l’environnement de build Cloudflare Pages

Spécificités de l’environnement de build Pages

Avant de diagnostiquer, une chose essentielle : l’environnement de build Cloudflare Pages diffère fondamentalement de votre machine locale. Souvent, l’échec de déploiement Pages n’est pas une erreur de code, mais une différence d’environnement.

Configuration par défaut :

• Système d’exploitation : Ubuntu (Build System V2 utilise Ubuntu 22)
• Version Node : 18.17.1 (oui, assez ancienne)
• Gestionnaire de paquets : npm clean-install par défaut, pas npm install
• Timeout de build : limite stricte de 20 minutes
• Taille Worker : limite de 10 Mo

Pourquoi Node si ancien ? Cloudflare privilégie la stabilité. Mais beaucoup de nouveaux paquets exigent Node >= 18.18.0 ou >= 20.0.0, d’où les conflits.

Trois différences clés avec l’environnement local :

1. Sensibilité à la casse du système de fichiers : sous Windows ou Mac, import Header from './header' fonctionne même si le fichier est Header.js. Sous Linux, la casse doit correspondre exactement. Piège souvent négligé.

2. Différences réseau : en local vous pouvez utiliser un miroir npm ; Pages se connecte au registre officiel, parfois avec timeout.

3. Commande de build par défaut : Cloudflare exécute npm clean-install --progress=false avant votre build command. Bien plus strict que npm install ; si package-lock.json et package.json ne correspondent pas, erreur.

Méthode de localisation rapide

Vous savez que l’environnement diffère. Comment trouver la vraie cause ?

Étape 1 : lire les logs de build

Les logs font souvent des centaines de lignes, mais quelques points suffisent :

# Trouver le dernier ERR! ou ERROR
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
# Ou les erreurs Vite/Webpack
[vite]: Rollup failed to resolve import
# Ou les erreurs Git
fatal: unable to access repository

Mon expérience : chercher « ERR! » (avec le point d’exclamation), remonter 3-5 lignes — la cause y est généralement.

Étape 2 : sauvegarder le Deployment ID

À chaque échec, Cloudflare génère un Deployment ID unique, visible dans la barre d’adresse :

https://dash.cloudflare.com/xxx/pages/view/your-project/a398d794-7322-4c97-96d9-40b5140a8d9b
                                                          ↑ Deployment ID

Ce ID est crucial pour le support Cloudflare ou une demande d’aide communautaire.

Étape 3 : reproduire en local

Étape souvent négligée. Reproduisez sous Linux :

# Méthode 1 : Docker Ubuntu 22
docker run -it ubuntu:22.04 bash
# Méthode 2 : npm ci strict (comme Pages)
npm ci
# Méthode 3 : version Node via nvm
nvm use 18.17.1

Si npm ci échoue en local, le problème est dans les dépendances. Si Node 18.17.1 fait planter, c’est la compatibilité de version.

Partie 2 : 8 scénarios d’échec courants et leurs solutions

Problème 1 : échec d’installation des dépendances (erreur npm install)

Messages d’erreur typiques :

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! Fix the upstream dependency conflict, or retry this command
npm ERR! with --force or --legacy-peer-deps
ou
npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network Socket timeout

Cas le plus fréquent. npm install OK en local, ERESOLVE sur Pages. Raison : Cloudflare utilise npm ci par défaut, très strict.

Causes :

1. npm clean-install ne résout pas automatiquement les conflits peer dependency
2. package-lock.json et package.json désynchronisés
3. Timeout réseau (registre npm officiel inaccessible)

Solutions (par ordre de recommandation) :

Solution 1 : ignorer l’installation par défaut, commande personnalisée

# Variable d'environnement dans les paramètres Pages
SKIP_DEPENDENCY_INSTALL=true
# Puis modifier la Build command
npm install --legacy-peer-deps && npm run build

Indique à Cloudflare de ne pas utiliser sa commande par défaut.

Solution 2 : corriger package-lock.json

# Régénérer le lock file en local
rm package-lock.json
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"
git push

Parfois le lock file est simplement corrompu.

Solution 3 : GitHub Actions pour le build

Si les deux précédentes échouent, problème plus complexe. GitHub Actions + cloudflare/pages-action pour contrôler l’environnement :

# .github/workflows/deploy.yml
- name: Install dependencies
  run: npm install --force
- name: Build
  run: npm run build
- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1

Prévention : exécuter npm ci régulièrement en local.

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

Tester l'MVP →Pub

Problème 2 : incompatibilité de version Node

Messages d’erreur typiques :

ERR_PNPM_UNSUPPORTED_ENGINE Unsupported environment
This package requires Node.js version ^18.18.0 or >=20.0.0
ou
The engine "node" is incompatible with this module.
Expected version ">=18.18.0". Got "18.17.1"

Node trop ancien. Beaucoup de paquets (TypeScript ESLint, Next.js 14+) exigent Node >= 18.18.0 ; Pages par défaut 18.17.1.

Solutions (une suffit) :

Solution 1 : variable d’environnement (recommandé)

Dans Cloudflare Pages Settings > Environment variables :

Nom: NODE_VERSION
Valeur: 20.11.0

Méthode officielle, simple et directe.

Solution 2 : fichier .node-version

echo "20.11.0" > .node-version
git add .node-version
git commit -m "chore: specify Node version for Cloudflare Pages"

Solution 3 : fichier .nvmrc

echo "20.11.0" > .nvmrc

Bonnes pratiques : utiliser variable d’environnement et .node-version pour cohérence local/production. Choisir une version LTS stable (ex. 20.11.0).

Problème 3 : timeout de build (plus de 20 minutes)

Symptôme typique :

Les logs montrent exactement 20 minutes puis arrêt, sans message d’erreur explicite :

Build exceeded maximum time of 20 minutes

Frustrant — peu d’information. Souvent gros projet ou trop de dépendances.

Causes :

• Trop de dépendances, npm install seul prend 15 minutes
• Script de build avec opérations redondantes
• Cache de build mal exploité

Solutions :

Solution 1 : vider le cache de build

Parfois le cache devient un fardeau :

Settings > Builds & deployments > Clear build cache

Reconstruire — plusieurs cas résolus ainsi.

Solution 2 : analyser et optimiser les dépendances

# Projet Next.js
npm install --save-dev @next/bundle-analyzer
# Puis dans next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer({
  // votre config
})

Exécuter ANALYZE=true npm run build. J’ai remplacé moment.js par day.js : -3 minutes de build.

Solution 3 : déplacer certaines tâches vers CI

typecheck, lint dans GitHub Actions ; Pages ne fait que le build :

// package.json
{
  "scripts": {
    "build": "next build",
    "build:full": "npm run typecheck && npm run lint && npm run build"
  }
}

Solution 4 : utiliser pnpm

Installation plus rapide. Build command :

Build command: pnpm install && pnpm run build

Problème 4 : erreur de résolution de module (Module not found)

Messages d’erreur typiques :

Module not found: Error: Can't resolve './App' in '/opt/buildhome/repo/src'
Did you mean 'App.js'?
ou
[vite]: Rollup failed to resolve import '/src/components/Snackbar'
from '/opt/buildhome/repo/src/pages/Login.jsx'

Erreur insidieuse : OK en local, module introuvable sur Pages. 99 % des cas : problème de casse.

Cause :

Linux distingue strictement la casse ; Windows et macOS non. import App from './app' avec fichier App.js : OK sous Windows, erreur sous Linux.

Solutions :

Solution 1 : corriger tous les chemins d’import

Vérifier que la casse correspond exactement :

// ❌ Incorrect
import Header from './header';  // fichier Header.jsx
// ✅ Correct
import Header from './Header';

Vérification manuelle fastidieuse. Règle ESLint recommandée :

// .eslintrc.js
module.exports = {
  rules: {
    'import/no-unresolved': 'error',
  }
}

Solution 2 : alias de chemins

// vite.config.js
export default {
  resolve: {
    alias: {
      '@': '/src',
      '@components': '/src/components'
    }
  }
}
// Import avec alias
import Header from '@components/Header';

Solution 3 : astuce communautaire

Un utilisateur a signalé une solution étrange mais efficace : renommer le dossier, commit, puis renommer à nouveau. Peut-être un problème de cache. À essayer si les autres solutions échouent.

Problème 5 : erreur de configuration des variables d’environnement

Symptômes typiques :

console.log(process.env.API_KEY); // undefined

Ou erreur de build indiquant une variable manquante.

Causes :

Confusion entre variables au build et au runtime. Conventions de nommage différentes selon le framework.

Point clé :

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

Commencer →Pub

Deux types sur Cloudflare Pages :

1. Variables au build : disponibles pendant npm run build, compilées dans le code
2. Variables au runtime : uniquement dans les Functions edge

Site statique pur (HTML/JS) : pas de variables runtime.

Solutions :

Solution 1 : configurer correctement le type

Cocher Production et Preview ; cocher Build si nécessaire au build.

Solution 2 : conventions de nommage du framework

# Vite : préfixe VITE_
VITE_API_KEY=xxx
# Next.js public : préfixe NEXT_PUBLIC_
NEXT_PUBLIC_API_KEY=xxx
# Nuxt : runtimeConfig dans nuxt.config.js

Solution 3 : secrets pour les informations sensibles

Deux types : Text (visible) et Secret (chiffré). API key, mots de passe : toujours Secret.

Bonnes pratiques :

1. Local : fichier .env.local (dans .gitignore)
2. Production : variables Cloudflare Pages
3. Valeurs différentes par environnement (Preview = API test, Production = API prod)

Problème 6 : problèmes d’intégration Git

Symptômes typiques :

• Impossible d’autoriser l’accès au dépôt
• Erreur : « This repository is already in use by another Pages project »
• Push sans déclenchement automatique du build

Causes :

Autorisation GitHub/GitLab, ou limitation Cloudflare (un dépôt par compte).

Solutions :

Solution 1 : réautoriser l’app GitHub

Settings > Applications > Cloudflare Pages > Configure > Uninstall

Reconnecter le dépôt dans le Dashboard Cloudflare.

Solution 2 : vérifier l’utilisation du dépôt

Si dépôt déjà utilisé, vérifier plusieurs comptes Cloudflare. Supprimer le projet Pages sur les autres comptes.

Solution 3 : permissions GitHub

Au minimum rôle Maintainer. Contributor seul : connexion impossible.

Solution 4 : éviter les caractères spéciaux

Pas d’emoji dans les messages de commit — peut empêcher le déclenchement du build.

Limitation connue : les PR de dépôts forkés ne déclenchent pas de preview. Cloudflare prévoit le support, pas encore disponible.

Problème 7 : échec de déploiement Functions

Symptômes typiques :

Build réussi mais échec au déploiement final, logs peu informatifs. Ou :

Build failed: Functions bundle size exceeding limit

Causes :

• Bundle Worker > 10 Mo
• Bindings Functions (KV, D1, R2) mal configurés
• API Node.js spécifiques non supportées en edge

Solutions :

Solution 1 : analyser la taille du bundle Functions

npm install --save-dev @next/bundle-analyzer

Souvent absence de tree-shaking.

Solution 2 : optimiser l’adaptateur Astro/SvelteKit

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'hybrid',
  adapter: cloudflare({
    mode: 'directory',
  }),
};

Astro embarque par défaut les pages pré-rendues dans Functions. mode: 'directory' corrige cela.

Solution 3 : vérifier les Bindings

Settings > Functions > Bindings

KV, D1, R2 correctement configurés.

Solution 4 : éviter les API Node.js spécifiques

Workers = V8, pas Node.js complet. Non disponibles :

• fs
• path (partiel)
• child_process
• net / http (utiliser fetch)

Déplacer la logique au build si nécessaire.

Problème 8 : cache et domaine personnalisé

Symptômes typiques :

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

Obtenir -15 % →Pub

• Déploiement réussi mais ancien contenu affiché
• Domaine personnalisé en 404, .pages.dev OK
• Page d’accueil 404 Not Found

Causes :

• Page Rules Cloudflare interférant avec le cache Pages
• DNS du domaine personnalisé mal configuré
• Absence de index.html

Solutions :

Solution 1 : supprimer la Page Rule Cache Everything

Si le domaine est Proxied (nuage orange), vérifier :

Rules > Page Rules

Supprimer toute règle « Cache Everything ». Pages a son propre mécanisme de cache.

Solution 2 : domaine personnalisé en DNS Only

DNS > Records > cliquer l'enregistrement > DNS Only

Sans proxy Cloudflare, connexion directe à Pages.

Solution 3 : vérifier index.html

Si la racine affiche 404, vérifier index.html dans le répertoire de sortie. Vérifier « Build output directory » dans Pages.

Solution 4 : purger le cache manuellement

Caching > Configuration > Purge Everything

Attention : purge tout le cache de la Zone.

Partie 3 : bonnes pratiques préventives

Configuration de build recommandée

Mieux vaut configurer dès le départ :

1. Spécifier explicitement la version Node

# Fichier .node-version
20.11.0
# Variable d'environnement Cloudflare Pages
NODE_VERSION=20.11.0

2. Commandes de build différentes par branche

Via CF_PAGES_BRANCH :

// package.json
{
  "scripts": {
    "build": "node scripts/build.js",
    "build:production": "next build",
    "build:preview": "next build && next export"
  }
}

// scripts/build.js
const branch = process.env.CF_PAGES_BRANCH || 'main';
const command = branch === 'main' ? 'build:production' : 'build:preview';
// exécuter la commande correspondante

3. Monorepo : répertoire racine correct

Avec pnpm workspace ou Turborepo :

Root directory: apps/web
Build command: pnpm run build

Surveillance et techniques de debug

1. Environnement de debug local

Docker simulant Pages :

# Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y nodejs npm
RUN node -v
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

2. Cloudflare Status

Parfois l’échec vient de Cloudflare lui-même :

https://www.cloudflarestatus.com/

Si Pages est en panne, attendre la résolution.

3. Quand contacter le support Cloudflare

Si toutes les solutions échouent, suspicion de bug plateforme, ou demande d’augmentation des limites (utilisateurs payants) — contacter le support avec Deployment ID et logs détaillés.

Conclusion

Les échecs de build CF Pages se réduisent à quelques catégories. Dans 90 % des cas : différences d’environnement (Node, casse des fichiers), configuration des dépendances (package-lock.json, peer dependency), ou mauvaise compréhension du fonctionnement Pages (variables d’environnement, cache).

Méthode systématique :

1. Lire les logs pour trouver le vrai message d’erreur
2. Identifier la catégorie (dépendances, version, chemins, config)
3. Reproduire en local
4. Appliquer la solution correspondante
5. Configurer préventivement pour éviter la récidive

Gardez cet article comme guide de dépannage. Prochain échec de build : suivez cette méthode, résolution probable en 10 minutes. Quand le « ✓ Deployed » vert apparaît, le soulagement est incomparable.

D’autres problèmes Cloudflare Pages ? Partagez en commentaire — cela peut aider d’autres développeurs.