Déploiement Vercel qui échoue : causes et solutions

Le deploy Vercel est rouge — et maintenant ?

Un push sur main, la barre de progression Vercel qui tourne, puis le bandeau rouge : “Build Failed”. Ou pire : le build passe au vert, mais le site affiche une 404 sèche. Ces situations arrivent bien plus souvent qu’on ne le pense, même sur des projets soignés.

La bonne nouvelle : dans 90 % des cas, la cause est lisible dans les logs de build, et la correction prend moins de dix minutes. Ce guide parcourt les échecs les plus fréquents, dans l’ordre du plus simple au plus technique.

Pourquoi ça arrive : les vraies causes

Avant de fouiller les logs, voici les suspects habituels :

• Mauvaise version de Node.js — le projet tourne sur Node 18 en local, Vercel utilise Node 20 (ou 16) par défaut.
• Dépendances manquantes ou conflictuelles — un package.json incomplet, un lockfile désynchronisé, ou un package en devDependencies alors qu’il est requis au build.
• Variables d’environnement absentes — le code référence process.env.NEXT_PUBLIC_API_URL mais la variable n’existe pas côté Vercel.
• Output Directory incorrect — Vercel cherche le dossier dist ou .next là où le framework produit autre chose.
• Framework mal détecté — Vercel auto-détecte le framework ; si la détection rate, la commande de build est fausse.
• Erreurs TypeScript ou ESLint bloquantes — certains projets Next.js ont "strict": true et font échouer le build sur un simple warning.
• Timeout de build — un build qui dépasse 45 minutes est tué automatiquement.

1. Lire les logs de build correctement

C’est le point de départ obligatoire. Beaucoup de développeurs voient “Build Failed” et tentent des correctifs à l’aveugle.

Où trouver les logs :

1. Dashboard Vercel → ton projet → onglet Deployments.
2. Clique sur le déploiement en échec (icône rouge).
3. Onglet Build Logs — fais défiler jusqu’au bloc rouge, souvent précédé d’un Error: ou npm ERR!.

Ce qu’il faut chercher :

• La dernière ligne avant l’erreur : c’est elle qui indique l’étape qui a planté.
• Les mentions Cannot find module, ENOENT, SyntaxError, Type error — chacune pointe vers une cause précise.
• Le code de sortie : exit code 1 = erreur applicative, exit code 127 = commande introuvable.

2. Corriger la version de Node.js

Si les logs mentionnent une erreur de syntaxe sur du code pourtant valide, ou engine "node" is incompatible, le problème vient probablement de là.

Solution : déclare la version dans package.json :

"engines": {
  "node": "20.x"
}

Ou dans le dashboard Vercel : Settings → General → Node.js Version — choisis la même version que ton environnement local (node -v).

3. Réparer les dépendances

Un npm install local ne suffit pas : Vercel exécute npm ci (ou yarn install --frozen-lockfile), qui est strict sur le lockfile.

Étapes :

1. Supprime node_modules et ton lockfile en local.
2. Relance npm install (ou yarn) pour régénérer un lockfile propre.
3. Committe et pousse package-lock.json ou yarn.lock.
4. Si un module est en devDependencies mais utilisé au build (ex : un loader Webpack, un plugin Babel), déplace-le dans dependencies.

Cas particulier des monorepos : si ton projet est dans un sous-dossier, configure Root Directory dans Vercel → Settings → General.

4. Ajouter les variables d’environnement manquantes

C’est la cause numéro un des builds qui passent en local mais échouent sur Vercel. Le code lit process.env.DATABASE_URL, la variable existe dans ton .env local (non commité, c’est normal), mais Vercel ne la connaît pas.

Solution :

1. Vercel Dashboard → ton projet → Settings → Environment Variables.
2. Ajoute chaque variable nécessaire, en précisant l’environnement : Production, Preview, Development.
3. Pour les variables exposées côté client en Next.js, le nom doit commencer par NEXT_PUBLIC_.
4. Après avoir ajouté des variables, relance un nouveau déploiement — les variables ne s’appliquent pas rétroactivement au build en cours.

Attention : ne committe jamais ton .env dans le repo. Utilise .env.local pour le local, et les secrets Vercel pour la prod.

5. Corriger l’Output Directory et le Framework

Si le build passe mais que le site affiche une 404 générale, Vercel sert peut-être le mauvais dossier.

Vérification :

• Vercel Dashboard → Settings → Build & Development Settings.
• Vérifie que Framework Preset correspond à ton vrai framework (Next.js, Astro, Vite, SvelteKit…).
• Vérifie Output Directory : Next.js → .next, Astro → dist, Vite → dist, Create React App → build.

Si tu as un script de build custom, désactive la détection automatique et renseigne manuellement la commande de build et le dossier de sortie.

Pour les projets Astro, l’article domaine perso sur Vercel/Netlify couvre les réglages DNS et SSL qui suivent naturellement une fois le build stabilisé.

6. Gérer les erreurs TypeScript et ESLint bloquantes

Next.js 13+ fait échouer le build par défaut sur les erreurs TypeScript. Si les logs affichent Type error: ..., deux options :

Option A (recommandée) — corriger l’erreur : c’est plus propre et évite d’accumuler de la dette.

Option B — désactiver temporairement : dans next.config.js :

module.exports = {
  typescript: { ignoreBuildErrors: true },
  eslint: { ignoreDuringBuilds: true },
}

À n’utiliser que pour débloquer un déploiement urgent, pas comme solution permanente.

7. 404 après un deploy réussi : domaine et routing

Le build est vert, l’URL *.vercel.app fonctionne, mais ton domaine custom retourne 404. Les causes possibles :

• Domaine non vérifié dans Vercel → Settings → Domains : un badge orange indique une vérification en attente. Ajoute l’enregistrement DNS demandé (CNAME ou A record) chez ton registrar.
• Mauvais projet lié — le domaine pointe vers un autre projet Vercel.
• Routing SPA manquant — pour une SPA Vite/React sans SSR, toutes les routes doivent être redirigées vers index.html. Crée un fichier vercel.json :

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Tableau récapitulatif

Quand passer la main à un pro

Si après ces étapes les logs restent inexplicables — erreurs de compilation obscures, conflits de dépendances en cascade, configuration monorepo complexe — c’est le signe d’une dette technique qui dépasse un simple correctif. Un déploiement Vercel instable finit souvent par révéler des problèmes plus profonds : architecture de projet bancale, maintenance absente, ou stack choisie sans anticiper les contraintes de déploiement. Si tu choisis une stack moderne comme Next.js ou Astro, les performances et Core Web Vitals que tu vises ne se matérialiseront que si le pipeline de déploiement est fiable de bout en bout.

Un build qui plante à chaque release, c’est du temps perdu à chaque itération — et ça se chiffre vite.