Variables d'environnement

Les variables d'environnement permettent de séparer la configuration du code : clés API, URLs de base de données, feature flags. La valeur change selon le contexte sans toucher au source. Vercel en fait un citoyen de première classe avec trois environnements distincts et une CLI dédiée.

Les trois environnements Vercel

Chaque variable peut être scoped sur un ou plusieurs environnements :

L'environnement Development est utilisé pour le développement local, avec vercel dev ou après un vercel env pull. Il reçoit des variables distinctes que tu peux récupérer sur ta machine sans exposer les secrets de production.

Une variable peut couvrir plusieurs environnements à la fois : Production + Preview, Development seul, ou les trois ensemble. Tu choisis au moment de la créer.

Ajouter une variable depuis le dashboard

C'est le chemin le plus direct pour gérer quelques variables ponctuelles.

1. Dans le dashboard Vercel, ouvre ton projet, puis Settings > Environment Variables.
2. Clique sur Add.
3. Renseigne le Name (ex : DATABASE_URL) et la Value.
4. Coche les environnements cibles (Production, Preview, Development, ou une combinaison).
5. Clique sur Save.

Ajouter une variable via le CLI

Pratique quand tu travailles déjà dans le terminal ou que tu veux scripter la configuration.

$vercel env add DATABASE_URL production

Le CLI te demande la valeur de façon interactive (elle n'apparaît pas dans l'historique shell). Pour cibler plusieurs environnements, ajoute-les séparément ou omets l'environnement pour être guidé par un menu interactif.

$vercel env add DATABASE_URL

Sans argument d'environnement, le CLI affiche un sélecteur : Production, Preview, Development. Tu peux en cocher plusieurs.

Récupérer les variables de développement en local

Vercel garde les variables Development dans le cloud. Pour les utiliser localement avec next dev (ou tout autre outil qui lit .env.local), exécute :

$vercel env pull .env.local

Cette commande crée ou écrase .env.local dans le dossier courant avec toutes les variables de l'environnement Development de ton projet.

Lire une variable dans ton code Next.js

Vercel injecte les variables comme des variables d'environnement Node.js standard. Dans ton code :

// Server-only (API routes, Server Components, getServerSideProps)
const dbUrl = process.env.DATABASE_URL

// Exposée au navigateur - préfixe NEXT_PUBLIC_ obligatoire
const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL

La distinction est importante :

• Sans préfixe (process.env.FOO) : disponible uniquement côté serveur. Next.js retire automatiquement ces valeurs du bundle client. Utilise ce format pour les secrets.
• Avec NEXT_PUBLIC_ (process.env.NEXT_PUBLIC_FOO) : inlinée dans le bundle JavaScript envoyé au navigateur. Tout le monde peut la lire dans le source. N'y mets jamais un secret, une clé API privée, ou un token.

Chiffrement et sécurité

Vercel chiffre toutes les valeurs au repos, quel que soit l'environnement (Production, Preview, Development). Les valeurs restent accessibles au build et à l'exécution dans le conteneur Vercel, mais ne sont pas exposées en clair dans les logs ou les réponses API publiques.