Kuinka ympäristömuuttujat toimivat Next.js:ssä?

Question

Accepted Answer

Next.js lataa ympäristömuuttujat `.env`-tiedostoista, tärkeän turvallisuussäännön kanssa: muuttujat ovat **oletuksena vain palvelimen puolella**, ja vain ne, joiden etuliite on `NEXT_PUBLIC_`, paljastetaan selaimelle.

## Tiedostot

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

## Kriittinen etuliitesääntö

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

Tämä etuliitesääntö on **turvallisuusominaisuus**: se estää sinua lähettämästä vahingossa tietokantasalasanoja tai API-salaisuuksia asiakkaalle. Muuttuja ilman etuliitettä ei yksinkertaisesti ole olemassa selaimen paketeissa.

## Kuinka NEXT_PUBLIC-arvot upotetaan

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

Koska ne upotetaan rakennusajalla, `NEXT_PUBLIC_`-arvon muuttaminen vaatii **uudelleenrakentamisen** — eikä sinun pitäisi koskaan laittaa todellisia salaisuuksia etuliitteen taakse (ne näkyisivät paketissa kaikille).

## Parhaat käytännöt

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

## Miksi tämä on tärkeää

Vain palvelimen käytössä oleva malli oletuksena `NEXT_PUBLIC_`-valinnaisella on Next.js:n suoja salaisuuksien vuotamista vastaan asiakkaalle — yleinen, vakava virhe.

Ymmärtäminen siitä, mitkä muuttujat saavuttavat selaimen, että julkiset upotetaan rakennusajalla, ja missä salaisuudet tallennetaan (gitignored `.env.local`), on olennaista sekä toiminnallisuuden että turvallisuuden kannalta.