nextjs-env-variables

Next.js 環境変数の構成

Next.js の環境変数管理に関する完全ガイドです。

ファイル構成

my-nextjs-app/
├── .env                      # Shared defaults (committed)
├── .env.local               # Local secrets (gitignored)
├── .env.development         # Development defaults (committed)
├── .env.development.local   # Local dev overrides (gitignored)
├── .env.production          # Production defaults (committed)
├── .env.production.local    # Production secrets (gitignored)
├── .env.test                # Test environment (committed)
└── .env.example             # Documentation (committed)

ファイルの優先順位

Next.js は次の順序でファイルを読み込みます（上にあるほど優先度が高くなります）。

1. .env.$(NODE_ENV).local（例：.env.production.local）
2. .env.local（テスト環境では読み込まれません）
3. .env.$(NODE_ENV)（例：.env.production）
4. .env

例：本番環境で DATABASE_URL が .env と .env.production.local の両方に定義されている場合、.env.production.local の値が優先されます。

変数の種類

クライアント側の変数（NEXT_PUBLIC_*）

ブラウザーに公開されます。NEXT_PUBLIC_ というプレフィックスを付ける必要があります。

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
NEXT_PUBLIC_SITE_NAME=My Awesome Site
NEXT_PUBLIC_ENABLE_FEATURE_X=true

コード内でのアクセス方法：

// Works in both client and server
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// Usage in components
export default function MyComponent() {
  return <div>API: {process.env.NEXT_PUBLIC_API_URL}</div>;
}

⚠️ セキュリティに関する警告：NEXT_PUBLIC_* 変数にシークレットを絶対に設定しないでください！

# ❌ WRONG - Secret exposed to browser
NEXT_PUBLIC_API_SECRET=sk_live_abc123

# ✅ CORRECT - Secret only on server
API_SECRET=sk_live_abc123

サーバー側の変数

サーバー側のコード（API ルート、getServerSideProps など）でのみ使用できます。

# .env.local
DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=super-secret-jwt-key-do-not-expose
STRIPE_SECRET_KEY=sk_live_abc123
SMTP_PASSWORD=email-password-here

コード内でのアクセス方法：

// ✅ Works in API routes
export default async function handler(req, res) {
  const dbUrl = process.env.DATABASE_URL;
  // Use dbUrl...
}

// ✅ Works in getServerSideProps
export async function getServerSideProps() {
  const secret = process.env.JWT_SECRET;
  // Use secret...
}

// ❌ Does NOT work in components (browser)
export default function MyComponent() {
  const dbUrl = process.env.DATABASE_URL; // undefined!
}

ファイルの例

.env（コミット対象 — 共通のデフォルト値）

# Shared defaults for all environments
NEXT_PUBLIC_APP_NAME=My Next.js App
NEXT_PUBLIC_DEFAULT_LOCALE=en

# Database (overridden in .env.local)
DATABASE_URL=postgres://localhost:5432/dev

# External services (no secrets)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123

.env.local（Git 追跡対象外 — ローカルのシークレット）

# Local development secrets
DATABASE_URL=postgres://localhost:5432/mylocal
JWT_SECRET=dev-jwt-secret-change-in-production
STRIPE_SECRET_KEY=sk_test_local_key

# Local overrides
NEXT_PUBLIC_API_URL=http://localhost:4000/api

.env.production（コミット対象 — 本番環境のデフォルト値）

# Production environment defaults
NEXT_PUBLIC_API_URL=https://api.production.com
NEXT_PUBLIC_ANALYTICS_ID=UA-PROD-123456

# These will be overridden by platform env vars
DATABASE_URL=set-this-in-vercel
JWT_SECRET=set-this-in-vercel

.env.example（コミット対象 — ドキュメント）

# Copy this to .env.local and fill in actual values

# Client-side (browser accessible)
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
NEXT_PUBLIC_SITE_NAME=Your Site Name

# Server-side (secrets)
DATABASE_URL=postgres://user:password@host:5432/database  # pragma: allowlist secret
JWT_SECRET=your-jwt-secret-32-chars-minimum
STRIPE_SECRET_KEY=sk_live_your_stripe_key
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-smtp-password

よくあるパターン

データベースの設定

# Development (.env.local)
DATABASE_URL=postgres://localhost:5432/myapp_dev

# Production (Vercel Environment Variables)
DATABASE_URL=postgres://user:pass@prod-host:5432/myapp_prod  # pragma: allowlist secret

API キー

# Public keys (client-side)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_abc123

# Secret keys (server-side only)
STRIPE_SECRET_KEY=sk_live_xyz789

機能フラグ

# Toggle features
NEXT_PUBLIC_ENABLE_DARK_MODE=true
NEXT_PUBLIC_ENABLE_BETA_FEATURES=false

Vercel へのデプロイ

手順 1：Vercel で環境変数を追加する

1. Project Settings → Environment Variables に移動します
2. 各変数を追加します。
   • キー：DATABASE_URL
   • 値：postgres://...
   • 環境：Production、Preview、Development

手順 2：クライアント側とサーバー側の変数を分ける

Vercel はビルド時に NEXT_PUBLIC_* 変数を自動的に公開します。

# Vercel automatically handles:
NEXT_PUBLIC_API_URL=https://api.example.com  # ✅ Exposed to browser

# Server-only:
DATABASE_URL=postgres://...  # ✅ Not exposed to browser

手順 3：NEXT_PUBLIC_ 変数を変更した後に再ビルドする

⚠️ 重要：NEXT_PUBLIC_* 変数はビルド時にビルドに埋め込まれます。

Vercel でこれらを変更した場合は、再デプロイが必要です。

vercel --prod

検証のワークフロー

1. ローカル環境を検証する

# Check structure
python scripts/validate_env.py .env.local --framework nextjs

# Compare with .env.example
python scripts/validate_env.py .env.local --compare-with .env.example

# Check for security issues
python scripts/scan_exposed.py --check-gitignore

2. ファイルの優先順位を確認する

# List all .env files
ls -la .env*

# Validate each
for file in .env*; do
  echo "=== $file ==="
  python scripts/validate_env.py $file --framework nextjs
done

3. Vercel と同期する

# Compare local vs Vercel
python scripts/sync_secrets.py --platform vercel --compare

# Sync (dry-run first)
python scripts/sync_secrets.py --platform vercel --sync --dry-run

# Actually sync
python scripts/sync_secrets.py --platform vercel --sync --confirm

よくある問題

問題：ブラウザーで変数が未定義になる

症状：コンポーネント内で process.env.MY_VAR が undefined になります。

解決策：NEXT_PUBLIC_ プレフィックスを追加します。

# ❌ Wrong
API_URL=https://api.example.com

# ✅ Correct
NEXT_PUBLIC_API_URL=https://api.example.com

問題：変更した変数が反映されない

症状：Vercel で NEXT_PUBLIC_* 変数を変更したのに、アプリでは古い値が使われます。

解決策：再デプロイします（変数はビルドに埋め込まれます）。

vercel --prod

問題：ローカルでは動作するが、本番環境では動作しない

症状：.env.local を使うとアプリは動作しますが、本番環境では失敗します。

解決策：.env.local のすべての変数が Vercel に設定されていることを確認します。

# Compare
python scripts/sync_secrets.py --platform vercel --compare

# Find missing vars and add them in Vercel UI

セキュリティチェックリスト

• .gitignore に .env.local が含まれている
• .gitignore に .env.*.local が含まれている
• NEXT_PUBLIC_* 変数にシークレットが含まれていない
• 実際のシークレットを含む .env ファイルがコミットされていない
• .env.example には構成のみが記載され、実際の値は含まれていない
• シークレットはコミット対象のファイルではなく、Vercel に直接設定されている

参考資料

• Next.js 環境変数のドキュメント
• Vercel 環境変数

---

関連：validation.md | security.md | frameworks.md

関連スキル

Nextjs を使用する際は、以下のスキルがワークフローを強化します。

• react：Next.js コンポーネント向けの基本的な React パターンとフック
• tanstack-query：App Router と Server Components によるサーバー状態管理
• drizzle：Next.js のサーバーアクションと API ルート向けの型安全な ORM
• prisma：Next.js との優れた統合が特徴の代替 ORM
• test-driven-development：Next.js App Router、Server Components、API ルートのテスト

[バンドルにデプロイされている場合、これらのスキルで完全なドキュメントを参照できます]