5 erreurs de déploiement Vercel avec Next.js (et comment les corriger)

Ton projet Next.js tourne parfaitement en local, mais Vercel retourne une erreur au déploiement. C'est l'un des problèmes les plus frustrants en vibe coding — et dans 90% des cas, l'une de ces 5 erreurs en est la cause.

1. Variables d'environnement manquantes ou mal configurées

C'est de loin la cause n°1. Les variables .env.local ne sont jamais envoyées sur Vercel — tu dois les configurer manuellement dans Settings → Environment Variables.

Symptômes : Error: supabaseUrl is required, Cannot read properties of undefined, API qui retourne 500 en prod.

Fix :

• Va dans ton projet Vercel → Settings → Environment Variables
• Ajoute toutes les variables de ton .env.local
• Attention : les variables NEXT_PUBLIC_ sont côté client, les autres côté serveur uniquement
• Redéploie après ajout

2. Erreur TypeScript ou ESLint bloquante

Vercel exécute next build qui inclut la vérification TypeScript par défaut. Si ton code a des erreurs de types qui passent en local (souvent ignorées dans l'IDE), le build Vercel échoue.

Symptômes : Type error: Property 'x' does not exist on type 'y', ESLint: no-unused-vars

Fix rapide : Lance npx tsc --noEmit et npx eslint . en local pour voir les erreurs.

Fix permanent : Corrige les types. En dernier recours pour aller vite :

// next.config.mjs
export default {
  typescript: { ignoreBuildErrors: true },
  eslint: { ignoreDuringBuilds: true },
};

3. Import de module Node.js dans un Server Component ou Edge Runtime

Certains packages Node.js (fs, crypto, path, child_process) ne sont pas disponibles dans les Edge Functions ou les Server Components mal configurés.

Symptômes : Module not found: Can't resolve 'fs', Dynamic Code Evaluation not allowed

Fix : Vérifie que ces imports sont bien dans des routes API avec export const runtime = 'nodejs' ou déplace le code dans une fonction serveur classique.

4. Fonction serverless qui dépasse le timeout (10s sur plan gratuit)

Vercel Hobby a un timeout de 10 secondes par fonction. Si ton API fait des appels multiples à Supabase, OpenAI, ou d'autres services, tu peux dépasser cette limite.

Symptômes : 504 Gateway Timeout, erreurs aléatoires en production uniquement

Fix :

• Optimise les requêtes (parallélise avec Promise.all)
• Mets en cache les résultats avec unstable_cache ou Redis
• Passe au plan Pro Vercel (timeout 60s) si nécessaire

5. Conflit de dépendances ou version de Node.js différente

Vercel utilise Node.js 18 par défaut. Si tu développes en local avec Node.js 20/22, certaines API peuvent différer. De même, des packages qui s'installent différemment selon l'OS peuvent échouer.

Symptômes : Build qui réussit en local, échec sur Vercel avec des erreurs npm/yarn obscures

Fix : Spécifie la version Node.js dans package.json :

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

Et dans Vercel Settings → General → Node.js Version, sélectionne la même version.

Diagnostic rapide