Bagaimana pembolehubah persekitaran berfungsi dalam Next.js?

Question

Accepted Answer

Next.js memuatkan pembolehubah persekitaran daripada fail `.env`, dengan peraturan keselamatan yang penting: pembolehubah adalah **hanya pelayan secara lalai**, dan hanya yang bermula dengan awalan `NEXT_PUBLIC_` didedahkan ke penyemak imbas.

## Fail-fail

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

## Peraturan awalan kritikal

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

Peraturan awalan ini adalah **ciri keselamatan**: ia menghalang anda daripada secara tidak sengaja menghantar kata laluan pangkalan data atau rahasia API kepada klien. Pembolehubah tanpa awalan hanya tidak wujud dalam bundel penyemak imbas.

## Bagaimana nilai NEXT_PUBLIC_ tertanam

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

Kerana ia tersadai pada masa binaan, mengubah nilai `NEXT_PUBLIC_` memerlukan **pembinaan semula** — dan anda tidak boleh pernah meletakkan rahasia sebenar di belakang awalan (ia akan dilihat dalam bundel kepada sesiapa).

## Amalan terbaik

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

## Mengapa ia penting

Model hanya pelayan yang lalai dengan pilihan opt-in `NEXT_PUBLIC_` adalah halangan Next.js terhadap kebocoran rahasia ke klien — kesalahan biasa dan serius.

Memahami pembolehubah mana yang sampai ke penyemak imbas, bahawa nilai awam tersadai pada masa binaan, dan tempat menyimpan rahasia (`.env.local` diabaikan git) adalah penting untuk kedua-dua fungsi dan keselamatan.