Wie funktionieren Umgebungsvariablen in Next.js?

Question

Accepted Answer

Next.js lädt Umgebungsvariablen aus `.env`-Dateien, mit einer wichtigen Sicherheitsregel: Variablen sind **standardmäßig nur auf dem Server**, und nur diejenigen mit dem Präfix `NEXT_PUBLIC_` werden dem Browser zugänglich gemacht.

## Die Dateien

```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
```

## Die kritische Präfixregel

```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
```

Diese Präfixregel ist ein **Sicherheitsmerkmal**: Sie verhindert, dass Sie versehentlich Datenbankkennwörter oder API-Geheimnisse an den Client senden. Eine Variable ohne Präfix existiert einfach nicht in Browser-Bundles.

## Wie NEXT_PUBLIC-Werte eingefügt werden

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

Da sie zur Build-Zeit eingefügt werden, erfordert das Ändern eines `NEXT_PUBLIC_`-Werts ein **Rebuild** — und Sie sollten echte Geheimnisse niemals hinter das Präfix stellen (sie wären für jeden im Bundle sichtbar).

## Best Practices

```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)
```

## Warum es wichtig ist

Das Server-Only-by-Default-Modell mit dem `NEXT_PUBLIC_`-Opt-in ist Next.js's Schutzmaßnahme gegen das Durchsickern von Geheimnissen an den Client — ein häufiger, ernsthafter Fehler.

Zu verstehen, welche Variablen den Browser erreichen, dass öffentliche Variablen zur Build-Zeit eingefügt werden, und wo man Geheimnisse speichert (gitignorierte `.env.local`), ist sowohl für die Funktionalität als auch für die Sicherheit unerlässlich.