Jak działają zmienne środowiskowe w Next.js?

Question

Accepted Answer

Next.js ładuje zmienne środowiskowe z plików `.env` z ważną regułą bezpieczeństwa: zmienne są **domyślnie tylko na serwerze**, a tylko te z przedrostkiem `NEXT_PUBLIC_` są ujawniane przeglądarce.

## Pliki

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

## Krytyczna reguła przedrostka

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

Ta reguła przedrostka to **funkcja bezpieczeństwa**: zapobiega przypadkowemu wysłaniu haseł do bazy danych lub tajnych kluczy API do klienta. Zmienna bez przedrostka po prostu nie istnieje w pakietach przeglądarki.

## Jak wartości NEXT_PUBLIC są osadzane

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

Ponieważ są osadzane w czasie kompilacji, zmiana wartości `NEXT_PUBLIC_` wymaga **przebudowy** — i nigdy nie powinieneś umieszczać prawdziwych tajemnic za przedrostkiem (byłyby widoczne w pakiecie dla każdego).

## Najlepsze praktyki

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

## Dlaczego to ważne

Model serwer-tylko-domyślnie z opcją `NEXT_PUBLIC_` to zabezpieczenie Next.js przed wyciekiem tajemnic do klienta — powszechny, poważny błąd.

Zrozumienie, które zmienne docierają do przeglądarki, że wartości publiczne są osadzane w czasie kompilacji i gdzie przechowywać tajemnice (ignorowany `.env.local`) jest niezbędne zarówno dla funkcjonalności, jak i bezpieczeństwa.