Biến môi trường hoạt động như thế nào trong Next.js?

Question

Accepted Answer

Next.js nạp biến môi trường từ các file `.env`, với một quy tắc bảo mật quan trọng: biến **chỉ dành cho server theo mặc định**, và chỉ những biến có tiền tố `NEXT_PUBLIC_` mới được lộ ra browser.

## Các file

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

## Quy tắc tiền tố cốt yếu

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # chỉ server — KHÔNG bao giờ gửi tới browser
NEXT_PUBLIC_API_URL=https://api.example.com  # được lộ ra browser
```

```tsx
// Server Component / Route Handler / Server Action — đọc được mọi thứ
const db = process.env.DATABASE_URL;          // ✅ hoạt động trên server

// Client Component — chỉ có NEXT_PUBLIC_*
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ hoạt động
const secret = process.env.DATABASE_URL;      // ❌ undefined trong browser
```

Quy tắc tiền tố này là một **tính năng bảo mật**: nó ngăn bạn vô tình đưa mật khẩu database hay bí mật API tới client. Một biến không có tiền tố đơn giản là không tồn tại trong các bundle của browser.

## Cách các giá trị NEXT_PUBLIC được nhúng

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

Vì chúng được inline lúc build, thay đổi một giá trị `NEXT_PUBLIC_` đòi hỏi **build lại** — và bạn không bao giờ nên đặt bí mật thật sau tiền tố này (chúng sẽ hiện ra trong bundle cho bất kỳ ai).

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

## Tại sao điều này quan trọng

Mô hình chỉ-server-theo-mặc-định với cơ chế opt-in `NEXT_PUBLIC_` là lá chắn của Next.js chống rò rỉ bí mật tới client — một lỗi phổ biến và nghiêm trọng.

Hiểu biến nào tới được browser, biến công khai được inline lúc build, và nơi lưu bí mật (`.env.local` được gitignore) là thiết yếu cho cả chức năng lẫn bảo mật.