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

示例：在生产环境中，如果 .env 和 .env.production.local 中都定义了 DATABASE_URL，则采用 .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. 前往项目设置 → 环境变量
2. 添加每个变量：
   • 键：DATABASE_URL
   • 值：postgres://...
   • 环境：生产、预览、开发

步骤 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 时正常，但在生产环境中失败。

解决方案：确保在 Vercel 中设置 .env.local 中的所有变量：

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

# Find missing vars and add them in Vercel UI

安全检查清单

• .env.local 已添加到 .gitignore
• .env.*.local 已添加到 .gitignore
• 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 路由

[如果这些技能已部署在你的资源包中，可查看完整文档]