Next.js 中的环境变量是如何工作的？

Question

Accepted Answer

Next.js 从 `.env` 文件加载环境变量，遵循一条重要的安全规则：变量**默认仅限服务器**，只有以 `NEXT_PUBLIC_` 为前缀的变量才会暴露到浏览器。

## 文件

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

## 关键前缀规则

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

这个前缀规则是一项**安全特性**：它防止你意外地将数据库密码或 API 密钥泄露给客户端。没有前缀的变量在浏览器 bundle 中根本不存在。

## NEXT_PUBLIC_ 值如何被嵌入

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

因为它们在构建时被内联，改变 `NEXT_PUBLIC_` 值需要**重新构建** — 你永远不应该将真实密钥放在这个前缀后面（它们在 bundle 中对任何人都是可见的）。

## 最佳实践

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

## 为什么这很重要

默认仅限服务器的模型加上 `NEXT_PUBLIC_` 可选参与是 Next.js 防止向客户端泄露密钥的防护措施 — 这是一个常见的严重错误。

理解哪些变量会到达浏览器，公开变量在构建时被内联，以及在哪里存储密钥（被 gitignore 的 `.env.local`），对于功能性和安全性都至关重要。