Déploiement Netlify qui échoue : diagnostic et correction

Le build Netlify échoue — et le site est hors ligne

Ça arrive au pire moment : tu pousses un commit, Netlify lance le build, et quelques secondes plus tard : rouge. Soit le build s’arrête avec une erreur cryptique dans les logs, soit il “réussit” mais le site affiche une page blanche ou un 404 “Page not found” bien gênant.

La bonne nouvelle : dans 90 % des cas, l’origine est l’une des cinq causes suivantes — et toutes se règlent sans toucher à ton code métier. On les passe en revue dans l’ordre, du plus rapide à corriger au plus technique.

Pourquoi le build plante : les causes principales

• Base directory ou publish directory incorrects : Netlify ne sait pas où chercher le projet ni où est le dossier de sortie après compilation.
• Variables d’environnement absentes ou mal nommées : le build appelle process.env.MA_CLE qui vaut undefined → crash.
• Version Node incompatible : ton code tourne en Node 20 localement, Netlify utilise Node 16 par défaut → syntaxe non reconnue, package incompatible.
• Plugin Netlify mal configuré ou cassé : un plugin dans netlify.toml qui pointe vers une version obsolète bloque tout le pipeline.
• “Page not found” sur les routes SPA : le build réussit, mais Netlify ne sait pas que toutes les URLs doivent être renvoyées vers index.html (cas React, Vue, Nuxt en mode SPA…).

1. Vérifier le Base Directory et le Publish Directory

C’est l’erreur n°1 sur les monorepos ou les projets avec un sous-dossier frontend/.

Base Directory = le dossier depuis lequel Netlify lance la commande de build (ex : frontend/).
Publish Directory = le dossier que Netlify sert après le build (ex : frontend/dist ou build).

Où régler ça

• Interface Netlify → Site configuration → Build & deploy → Build settings.
• Ou dans netlify.toml à la racine du repo :

[build]
  base    = "frontend"
  command = "npm run build"
  publish = "frontend/dist"

Symptôme typique : No such file or directory: dist dans les logs, ou le build réussit mais le site est vide.

2. Ajouter les variables d’environnement

Les variables présentes dans ton .env local ne remontent jamais automatiquement sur Netlify — c’est voulu (sécurité). Il faut les déclarer à la main.

Chemin dans l’interface

Site configuration → Environment variables → Add a variable.

Recopie exactement les noms (VITE_API_URL, NEXT_PUBLIC_TOKEN…) et leurs valeurs. Attention : les frameworks modernes (Vite, Next.js) exigent un préfixe spécifique (VITE_ ou NEXT_PUBLIC_) pour exposer une variable côté client — sans ce préfixe, elle reste undefined même si elle est déclarée sur Netlify.

Après ajout, relance le build manuellement (Deploys → Trigger deploy → Clear cache and deploy site) : Netlify ne relit les variables que lors d’un nouveau build.

3. Fixer la version de Node

Par défaut, Netlify utilise souvent une version de Node en retard sur ce que les outils modernes attendent. La solution la plus fiable : déclarer la version dans le repo.

Option A — fichier .nvmrc

Crée un fichier .nvmrc à la racine :

20

Option B — netlify.toml

[build.environment]
  NODE_VERSION = "20"

Option C — variable d’environnement Netlify

Dans Site configuration → Environment variables : ajoute NODE_VERSION = 20.

Symptôme typique : SyntaxError: Unexpected token '?.' (optional chaining), ou un package qui exige Node ≥ 18 et refuse de s’installer.

4. Diagnostiquer un plugin Netlify cassé

Les plugins Netlify (définis dans netlify.toml ou installés via l’interface) s’exécutent à des étapes précises du pipeline. Un plugin obsolète peut bloquer le build entier sans raison évidente.

Que faire

1. Ouvre les logs de build complets (Deploy log → expand) et cherche la ligne Plugin X failed ou Error in onPreBuild.
2. Dans netlify.toml, vérifie le nom du package et sa version :

[[plugins]]
  package = "@netlify/plugin-nextjs"

3. Si la version est épinglée (@1.x.x), retire l’épinglage ou mets-la à jour.
4. En dernier recours : désactive le plugin temporairement (commente le bloc dans netlify.toml) pour vérifier que c’est bien lui qui bloque.

5. Corriger le “Page not found” sur une SPA

Le build a réussi, le site se charge sur / — mais dès qu’on navigue vers /contact ou qu’on recharge une page interne, Netlify répond 404. C’est le problème classique des Single Page Applications.

Pourquoi ça arrive

Netlify sert des fichiers statiques. Quand il reçoit une requête vers /contact, il cherche un fichier contact.html — qui n’existe pas (c’est React/Vue qui gère le routing côté client). Il faut lui dire de tout renvoyer vers index.html.

La solution : fichier _redirects

Crée un fichier _redirects dans le dossier publish (souvent public/ ou dist/) :

/*    /index.html   200

Cette règle dit : “pour toute URL qui ne correspond à aucun fichier, renvoie index.html avec un statut 200.”

Alternative : netlify.toml

[[redirects]]
  from   = "/*"
  to     = "/index.html"
  status = 200

⚠️ Si tu utilises Next.js en mode SSR ou Nuxt en mode universel, c’est le plugin @netlify/plugin-nextjs (voir étape 4) qui gère les redirections — pas _redirects. Ne les mélange pas.

Tableau récapitulatif

FAQ

Si après ces cinq étapes le build plante encore, les logs détaillés de Netlify contiennent presque toujours la ligne exacte qui pose problème — cherche le premier error ou ERR! dans le flux, tout ce qui précède n’est que contexte. Pour les projets plus complexes (Next.js App Router, Nuxt 3, configurations multi-sites), les interactions entre plugins et versions de runtime se compliquent vite : c’est là qu’un regard extérieur — celui de quelqu’un qui a déjà vu le même message d’erreur dix fois — fait gagner plusieurs heures. Si tu héberges par ailleurs sur Vercel, les mêmes principes DNS et SSL s’appliquent (un point de vigilance détaillé ici).

Pour les projets qui grandissent, la question du bon choix de stack technique se pose souvent au même moment qu’un build récalcitrant — autant en profiter pour s’assurer que l’outil est adapté à l’usage. Et si c’est la performance globale du site qui est en jeu, un déploiement propre est le prérequis n°1 avant d’optimiser quoi que ce soit d’autre.