Comment fonctionnent les variables d'environnement dans Next.js ?

Question

Accepted Answer

Next.js charge les variables d'environnement à partir des fichiers `.env`, avec une règle de sécurité importante : les variables sont **server-only par défaut**, et seules celles préfixées par `NEXT_PUBLIC_` sont exposées au navigateur.

## Les fichiers

```text
.env                # loaded in all environments
.env.local          # local overrides — GITIGNORED (put secrets here)
.env.development    # only in `next dev`
.env.production     # only in production builds
```

## La règle de préfixe critique

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com  # exposed to the browser
```

```tsx
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL;          // ✅ works on the server

// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ works
const secret = process.env.DATABASE_URL;      // ❌ undefined in the browser
```

Cette règle de préfixe est une **fonctionnalité de sécurité** : elle vous empêche d'envoyer accidentellement des mots de passe de base de données ou des secrets API au client. Une variable non préfixée n'existe simplement pas dans les bundles du navigateur.

## Comment les valeurs NEXT_PUBLIC_ sont intégrées

```text
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
```

Parce qu'elles sont inlinées au moment du build, modifier une valeur `NEXT_PUBLIC_` nécessite une **reconstruction** — et vous ne devriez jamais placer de vrais secrets derrière le préfixe (ils seraient visibles dans le bundle à tous).

## Bonnes pratiques

```text
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
```

## Pourquoi c'est important

Le modèle server-only par défaut avec l'opt-in `NEXT_PUBLIC_` est la protection de Next.js contre la fuite de secrets vers le client — une erreur courante et grave.

Comprendre quelles variables atteignent le navigateur, que les variables publiques sont inlinées au moment du build, et où stocker les secrets (`.env.local` ignoré par git) est essentiel pour la fonctionnalité et la sécurité.