Guide complet Next.js sur Vercel : variables d'environnement, domaines et monitoring

Page d’erreur 500 de Vercel dans le navigateur. Les variables d’environnement sont bien configurées dans le Dashboard Vercel, pourquoi l’API renvoie-t-elle toujours undefined ? J’ai vérifié .env.local trois fois, redéployé deux fois, même vidé le cache du navigateur — rien n’y fait.

Une demi-heure plus tard, j’ai découvert que le problème venait du préfixe NEXT_PUBLIC_.

Vous avez peut-être vécu la même chose : le projet Next.js tourne parfaitement en local, puis une fois déployé sur Vercel, tout devient imprévisible. Variables d’environnement inactives, domaine personnalisé qui renvoie 404 pendant des heures, certificat SSL qui provoque des redirections infinies.

Le flux de déploiement Vercel est effectivement simple, mais « simple » et « sans piège » ne sont pas synonymes. Les pièges cachés dans les détails peuvent être frustrants. Cet article vous guide à travers le déploiement complet de Next.js sur Vercel : du déploiement en un clic à la configuration correcte des variables d’environnement, en passant par le domaine personnalisé et le monitoring. Surtout, tous les pièges que la documentation ne mentionne pas — mais que vous rencontrerez — sont signalés.

Déploiement de base (en ligne en 5 minutes)

La bonne méthode pour le déploiement en un clic

Le flux Vercel est vraiment simple : pousser le code sur GitHub, connecter Vercel, quelques clics — terminé. Mais derrière cette simplicité se cachent de nombreux détails.

Commençons par le flux de base. Votre projet Next.js doit d’abord être poussé sur un dépôt Git (GitHub, GitLab ou Bitbucket). Ouvrez vercel.com, connectez-vous avec GitHub, cliquez sur « Import Project ».

Vercel scanne automatiquement votre dépôt, détecte Next.js et configure la commande de build et le répertoire de sortie. Vous n’avez presque rien à modifier :

Build Command: next build
Output Directory: .next
Install Command: npm install

Cliquez sur Deploy, attendez une ou deux minutes, et vous obtenez une URL your-project.vercel.app. À ce stade, Vercel a déjà distribué vos ressources statiques (JS, CSS, images) sur l’Edge Network — CDN mondial, prêt à l’emploi.

Mais voici un détail que les débutants oublient souvent : vérifiez votre package.json.

Si votre script build n’est pas next build, ou si les dépendances next, react, react-dom manquent, le déploiement échouera directement. J’ai vu quelqu’un écrire webpack comme script build, puis ne jamais réussir à déployer — Vercel n’avait tout simplement pas détecté Next.js.

Il y a aussi le workflow DPS — Develop, Preview, Ship. Ça sonne impressionnant, mais en réalité :

• Develop : développement local, npm run dev
• Preview : à chaque Pull Request ou push sur une branche non principale, Vercel génère automatiquement une URL de prévisualisation
• Ship : fusion sur main, Vercel déploie automatiquement en production

Ce mécanisme est très pratique. Vous développez une nouvelle fonctionnalité, ouvrez une PR, Vercel génère un lien your-project-git-feature-branch.vercel.app que vous pouvez envoyer au product manager ou aux testeurs, sans toucher à l’environnement de production.

Première chose après le déploiement : consulter les logs de build

Ne célébrez pas trop vite. Ouvrez le Dashboard Vercel, entrez dans votre projet, onglet « Deployments », cliquez sur le dernier déploiement.

Vous verrez les logs de build détaillés. Ils vous indiquent :

1. Durée d’installation des dépendances : plus d’une minute, c’est peut-être un node_modules trop volumineux ou un réseau lent
2. Avertissements pendant le build : erreurs TypeScript, règles ESLint
3. Nombre de pages statiques générées : Next.js indique quelles pages sont en SSG (Static Site Generation) et lesquelles en SSR (Server-Side Rendering)

Lors de mon premier déploiement, les logs affichaient une pile d’erreurs TypeScript, mais le déploiement avait quand même réussi. J’ai appris plus tard que Vercel n’empêche pas le déploiement pour des erreurs TypeScript — sauf si vous activez typescript.ignoreBuildErrors: false dans next.config.js.

Un autre point facile à négliger : un build réussi ne garantit pas que les pages fonctionnent.

J’ai vu des déploiements réussis avec une page 500 à l’ouverture — la cause était une route API utilisant le module Node.js fs pour lire un fichier local. Les Edge Functions ne supportent pas les opérations sur le système de fichiers. Les fonctions serverless Vercel sont isolées : chaque requête a son propre environnement, les fichiers ne persistent pas.

Configuration des variables d’environnement (le piège le plus fréquent)

Les trois niveaux d’environnement

Voici la partie la plus délicate. Les variables d’environnement peuvent être déroutantes — j’y ai passé une demi-heure lors de ma première configuration.

Vercel distingue trois environnements : Production, Preview et Development. En bref :

• Production : environnement officiel accessible aux utilisateurs, correspond à la branche main
• Preview : environnement de test généré automatiquement lors d’une PR ou d’un push sur une autre branche
• Development : environnement local avec npm run dev

Chaque environnement peut avoir des variables différentes. Par exemple, la chaîne de connexion à la base : production utilise la vraie base, preview la base de test, development la base locale.

Comment configurer en local ?

Créez .env.local ou .env.development à la racine du projet :

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here

.env.local est ignoré par Git (pensez à l’ajouter à .gitignore) — vos clés API ne fuiteront pas dans le dépôt.

Comment configurer sur Vercel ?

Dashboard Vercel → votre projet → Settings → Environment Variables.

Vous verrez trois cases : Production, Preview, Development. Cochez celles où la variable doit s’appliquer.

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

Commencer →Pub

Par exemple, une chaîne de connexion utilisée uniquement en production :

Name: DATABASE_URL
Value: postgresql://prod-server:5432/prod-db
Environment: ✅ Production

Après sauvegarde, redéployez — la variable sera active.

Piège courant : pas de redéploiement après modification.

Vercel ne redéploie pas automatiquement. Après avoir modifié une variable, déclenchez manuellement un déploiement (ou poussez du code) pour que la variable soit prise en compte.

Variables client vs serveur

C’est la partie la plus piégeuse. C’est exactement là que j’ai trébuché à trois heures du matin.

Les variables d’environnement Next.js se divisent en deux types :

1. Variables serveur : accessibles uniquement côté serveur (routes API, getServerSideProps, getStaticProps)
2. Variables client : préfixe NEXT_PUBLIC_ obligatoire, intégrées dans le JS du navigateur

Exemple :

# Variables serveur (sécurisées)
DATABASE_URL=postgresql://...
API_SECRET_KEY=abc123

# Variables client (exposées)
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Site

DATABASE_URL et API_SECRET_KEY ne sont accessibles que côté serveur. Mais NEXT_PUBLIC_API_BASE_URL est compilé directement dans le JS — n’importe qui peut l’ouvrir dans la console du navigateur.

Mon piège personnel :

J’avais une clé API à utiliser côté client pour appeler une API tierce. Sans le préfixe NEXT_PUBLIC_, le navigateur affichait undefined.

Après avoir ajouté le préfixe, la clé fonctionnait — mais elle était exposée dans le code du navigateur. N’importe qui ouvrant DevTools et cherchant NEXT_PUBLIC_ pouvait la voir.

La bonne approche ?

Ne pas appeler directement une API tierce depuis le client. Passer par une route API Next.js :

// app/api/data/route.ts (côté serveur)
export async function GET() {
  const res = await fetch('https://api.example.com', {
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET_KEY}` // sécurisé
    }
  })
  return res.json()
}

// app/page.tsx (côté client)
const data = await fetch('/api/data') // appeler notre propre API, sans exposer la clé

La clé API reste côté serveur et ne fuite jamais vers le navigateur.

Un détail : les variables NEXT_PUBLIC_ sont intégrées au moment du build, pas au runtime. Après modification, un rebuild est nécessaire.

Astuces de synchronisation des variables

En équipe, les variables d’environnement sont un casse-tête. Vous ne pouvez pas committer .env.local, mais les nouveaux collègues ne savent pas quoi configurer.

Vercel propose une commande :

vercel env pull .env.local

Elle récupère les variables Vercel (type Development) dans votre .env.local local.

Prérequis : installer Vercel CLI :

npm i -g vercel
vercel link  # associer votre projet
vercel env pull

Attention : seules les variables Development sont récupérées. Production et Preview ne le sont pas (pour des raisons de sécurité).

Autre astuce : un fichier .env.example comme modèle.

Créez .env.example à la racine, listez tous les noms de variables (sans valeurs) :

# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_API_BASE_URL=

Commettez ce fichier. Les nouveaux collègues le copient en .env.local et remplissent leurs valeurs.

La taille totale des variables Vercel est limitée à 64 Ko, 5 Ko par variable Edge Function. La plupart des projets n’atteignent pas ces limites, mais pour des clés publiques JWT ou des images en base64, vous pourriez les rencontrer.

Configuration du domaine personnalisé

Trois étapes pour lier un domaine

Un domaine your-project.vercel.app fait amateur, et *.vercel.app est bloqué en Chine. Pour que les utilisateurs chinois accèdent normalement, un domaine personnalisé est indispensable.

Étape 1 : ajouter le domaine dans Vercel

Dashboard Vercel → votre projet → Settings → Domains.

Cliquez « Add », saisissez votre domaine (example.com ou blog.example.com), puis Add.

Vercel analyse le domaine et indique les enregistrements DNS à configurer.

Étape 2 : configurer le DNS

Deux options : enregistrement A ou CNAME.

Pour un domaine racine (example.com) :

Type: A
Name: @
Value: 76.76.21.21

Pour un sous-domaine (blog.example.com) :

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

Configuration spéciale pour la Chine :

Si vos utilisateurs sont principalement en Chine, utilisez cname-china.vercel-dns.com à la place de cname.vercel-dns.com. C’est l’adresse CNAME optimisée par Vercel pour la Chine continentale.

Type: CNAME
Name: blog
Value: cname-china.vercel-dns.com

Ou un enregistrement A vers une IP adaptée :

Type: A
Name: @
Value: 76.223.126.88 ou 76.76.21.98

Après configuration DNS, attendez quelques minutes à quelques dizaines de minutes (selon votre registrar). Vercel détectera automatiquement la propagation.

Étape 3 : validation

Retournez au Dashboard Vercel, rafraîchissez. Si « Valid Configuration » apparaît en vert à côté du domaine, c’est bon.

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

Tester l'MVP →Pub

Ouvrez votre domaine dans le navigateur — vous devriez voir votre projet Next.js.

Piège courant : DNS mal configuré.

J’ai vu des CNAME avec le Name en domaine complet (blog.example.com) au lieu de blog. Résultat : échec de résolution DNS.

D’autres ont mis une mauvaise IP en A, ou le cache DNS du registrar n’a pas été rafraîchi — 404 pendant une demi-heure.

Configuration automatique du certificat SSL

Bonne nouvelle : Vercel demande automatiquement un certificat SSL (Let’s Encrypt). Aucune configuration supplémentaire — HTTPS fonctionne directement.

Une fois le domaine actif, Vercel demande le certificat en quelques minutes. Sur la page Domains, « Certificate Status: Provisioning » devient « Active ».

Accédez à https://example.com — le cadenas vert confirme le HTTPS.

Piège : certificat incompatible provoquant des redirections infinies.

Si vous configurez à la fois le domaine racine (example.com) et www (www.example.com), Vercel redirige l’un vers l’autre par défaut.

Mais si le DNS est mal configuré, ou si le certificat SSL n’a été émis que pour un seul domaine, vous obtenez des redirections infinies — le navigateur oscille entre http://example.com et https://www.example.com.

Solution : ajoutez example.com et www.example.com dans Vercel, avec un DNS correct pour les deux.

Certains registrars exigent le mode « chiffrement complet » en SSL/TLS. Le mode « flexible » peut provoquer une incompatibilité de certificat.

Comment vérifier que le SSL est actif ?

Ouvrez https://example.com, cliquez sur le cadenas, consultez les détails du certificat. « Issued by: Let’s Encrypt » confirme la configuration.

Ou en ligne de commande :

curl -I https://example.com

Vérifiez le code HTTP 200 et la présence de l’en-tête Strict-Transport-Security (HSTS).

Sous-domaines et stratégie multi-domaines

Configuration bidirectionnelle www et domaine racine

Beaucoup configurent example.com et www.example.com, puis redirigent l’un vers l’autre.

Dans Vercel : ajoutez les deux domaines sur la page Domains, Vercel gère la redirection. Choisissez « Primary Domain » dans Settings — l’autre redirige automatiquement.

Stratégie de domaines pour sites multilingues

Si votre Next.js supporte l’i18n, liez un sous-domaine par langue :

• en.example.com → version anglaise
• zh.example.com → version chinoise
• ja.example.com → version japonaise

Ajoutez ces sous-domaines dans Settings → Domains, puis configurez i18n dans next.config.js :

module.exports = {
  i18n: {
    locales: ['en', 'zh', 'ja'],
    defaultLocale: 'en',
    domains: [
      { domain: 'en.example.com', defaultLocale: 'en' },
      { domain: 'zh.example.com', defaultLocale: 'zh' },
      { domain: 'ja.example.com', defaultLocale: 'ja' },
    ],
  },
}

Domaine indépendant pour une branche Preview

Pour lier un domaine à l’environnement de prévisualisation (branche staging), ajoutez staging.example.com dans Domains et sélectionnez « Git Branch » = staging.

Chaque push sur staging déploie automatiquement sur staging.example.com, sans toucher à la production.

Monitoring et optimisation des performances

Vercel Analytics et Speed Insights

Une fois en ligne, vous voulez savoir : la page charge-t-elle vite ? L’expérience utilisateur est-elle bonne ? Y a-t-il des goulots ?

Vercel propose deux outils d’analyse gratuits : Analytics (comportement utilisateur) et Speed Insights (performance).

Intégration rapide de Speed Insights

Avec Next.js App Router (Next.js 13+), c’est très simple :

npm install @vercel/speed-insights

Ajoutez une ligne dans le layout racine :

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  )
}

Après déploiement, l’onglet « Speed Insights » du Dashboard Vercel commence à collecter des données.

Monitoring des Core Web Vitals

Speed Insights suit automatiquement les trois métriques clés définies par Google :

1. FCP (First Contentful Paint) : premier rendu de contenu. Valeur idéale < 1,8 s
2. LCP (Largest Contentful Paint) : rendu du plus grand élément. Valeur idéale < 2,5 s
3. CLS (Cumulative Layout Shift) : stabilité visuelle. Valeur idéale < 0,1

Ces données proviennent des vrais navigateurs (Real User Monitoring), pas du labo. Vous voyez les performances par région, appareil et navigateur.

Comment optimiser avec Speed Insights ?

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Exemple concret. Sur un projet, le LCP restait autour de 4 s, bien au-dessus des 2,5 s idéaux.

En creusant, le problème venait de l’image Hero de la page d’accueil — un PNG de 2 Mo, non compressé, sans le composant <Image> de Next.js.

Après conversion en WebP et utilisation de next/image, le LCP est passé à 1,8 s. Le score Speed Insights de 60 à 95.

C’est la valeur des données utilisateurs réelles. Un score labo élevé ne vaut pas l’expérience réelle.

Analytics pour le comportement utilisateur

Vercel Analytics indique :

• Pages les plus visitées
• Sources de trafic
• Répartition géographique
• Pages à fort taux de rebond

Gratuit pour les projets personnels (100 000 vues/mois), payant pour les projets commerciaux.

Configuration avancée

Commande de build personnalisée

Pour un flux de build particulier, allez dans Dashboard Vercel → Settings → Build & Development Settings.

Par exemple avec pnpm au lieu de npm :

Build Command: pnpm build
Install Command: pnpm install

Ou un script avant le build :

Build Command: npm run prebuild && npm run build

Edge Functions et Edge Middleware

Vercel exécute du code sur les nœuds edge mondiaux — plus rapide que les Serverless Functions classiques.

Si votre Next.js utilise Middleware, Vercel le déploie automatiquement en Edge Middleware. Authentification, redirection, A/B testing — tout peut se faire au edge sans retour à l’origine.

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request) {
  if (!request.cookies.get('token')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

Timeout des Serverless Functions

Les Serverless Functions Vercel ont un timeout par défaut de 10 secondes (plan gratuit). Si votre route API fait des opérations longues (appel API tierce, génération PDF), vous risquez le timeout.

Les plans payants permettent jusqu’à 60 secondes. Ou déplacez les opérations longues vers une file d’attente (Inngest, Trigger.dev) sans bloquer la requête HTTP.

Protection de déploiement : mot de passe pour Preview

Pour ne pas exposer publiquement l’environnement Preview, activez la protection par mot de passe dans Settings → Deployment Protection.

Cochez « Password Protection for Previews », définissez un mot de passe. L’accès à l’URL de preview exigera ce mot de passe.

Utile pour protéger des données sensibles ou des fonctionnalités inachevées.

Conclusion

Vous devriez maintenant avoir une vision claire du déploiement complet de Next.js sur Vercel.

Du déploiement en un clic aux trois niveaux de variables d’environnement, en passant par le domaine personnalisé, le certificat SSL, le monitoring et la configuration avancée — ce sont des sujets que vous rencontrerez en production.

Les variables d’environnement sont déroutantes, mais retenez le principe : variables serveur sans préfixe, variables client avec NEXT_PUBLIC_, clés API jamais exposées au client. Ce piège, je l’ai déjà pris pour vous.

La configuration de domaine semble simple, mais les détails DNS piègent facilement. Pour les utilisateurs en Chine, pensez à cname-china.vercel-dns.com ou 76.76.21.21 — sinon votre site peut être inaccessible.

Côté monitoring, Speed Insights est vraiment utile. Les données utilisateurs réelles valent mieux que les scores labo. LCP au-dessus de 2,5 s ? Vérifiez images, polices et rendu initial — souvent un ajustement suffit pour gagner 30 points.

Vous maîtrisez maintenant le flux complet. Ouvrez le terminal, poussez votre premier projet sur GitHub, connectez Vercel, et regardez le déploiement automatique se terminer — cette satisfaction vaut largement ces dix minutes de lecture.

Des questions ? Laissez un commentaire, j’essaierai d’y répondre. Bon déploiement !