Kaip veikia aplinkos kintamieji Next.js?

Question

Accepted Answer

Next.js įkelia aplinkos kintamuosius iš `.env` failų, su svarbia saugumo taisykle: kintamieji yra **tik serverio pagal numatytuosius nustatymus**, ir tik tie, kurie prasideda `NEXT_PUBLIC_` priešdėliu, yra atskleisti naršyklei.

## Failai

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

## Kritinis priešdėlio taisyklė

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

Šis priešdėlio taisyklė yra **saugumo ypatybė**: ji nuo jūs užkirsti kelią netyčia nusiųsti duomenų bazės slaptažodžius arba API paslapčius klientui. Kintamasis be priešdėlio paprasčiausiai neegzistuoja naršyklės paketose.

## Kaip NEXT_PUBLIC_ reikšmės yra įterptos

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

Dėl to, kad jie yra įterpti statybos metu, `NEXT_PUBLIC_` reikšmės pakeitimas reikalauja **perkompiliavimo** — ir jūs niekada neturėtumėte dėti tikrų paslapčių priešdėlio (jie būtų matomi pakete visiems).

## Geriausia praktika

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

## Kodėl tai svarbu

Tik serverio modelis su `NEXT_PUBLIC_` opt-in yra Next.js apsauga nuo paslapčių nutekinimo klientui — dažnas ir rimtas klaidus.

Supratimas, kurie kintamieji pasiekia naršyklę, kad viešosios reikšmės yra įterptos statybos metu, ir kur saugoti paslapčius (git'e nepaisomi `.env.local`) yra esminis ir funkcionalumui, ir saugumui.