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シークレットを誤ってクライアントに送信することを防ぎます。プレフィックスのない変数は単にブラウザバンドルに存在しません。

## NEXT_PUBLIC_値がどのように埋め込まれるか

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

ビルド時にインライン化されるため、`NEXT_PUBLIC_`値を変更するには**リビルド**が必要です。また、プレフィックスの後ろに本当のシークレットを置くべきではありません(バンドル内の誰もが見えるようになります)。

## ベストプラクティス

```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のクライアントへのシークレット漏洩防止の保護機能です。これは一般的で深刻な間違いです。

どの変数がブラウザに到達するか、公開変数はビルド時にインライン化されること、そしてシークレットをどこに保存するか(git無視される`.env.local`)を理解することは、機能性とセキュリティの両方に不可欠です。