环境变量配置

环境变量用于存储配置和密钥，不同环境（开发、测试、生产）使用不同的值。

为什么需要环境变量

安全：密钥不提交到代码仓库
灵活：不同环境使用不同配置
方便：修改配置不需要改代码

基本用法

本地开发

创建 .env.local 文件：

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your_secret_key
NEXT_PUBLIC_API_URL=http://localhost:3000/api

重要：.env.local 不要提交到 Git。

.gitignore

.env.local
.env*.local

读取环境变量

// Node.js / Next.js
const apiKey = process.env.API_KEY
const apiUrl = process.env.NEXT_PUBLIC_API_URL

前端 vs 后端环境变量

后端环境变量

只在服务端可用，不会暴露给浏览器：

DATABASE_URL=postgresql://...
API_SECRET=your_secret

前端环境变量

需要在浏览器中使用，必须加前缀：

# Next.js
NEXT_PUBLIC_API_URL=https://api.example.com

# Vite
VITE_API_URL=https://api.example.com

# Create React App
REACT_APP_API_URL=https://api.example.com

注意：前端环境变量会暴露给用户，不要放密钥。

托管平台配置

Vercel

进入项目 → Settings → Environment Variables
添加变量名和值
选择环境（Production / Preview / Development）
点击 Save
重新部署生效

通过 CLI：

vercel env add API_KEY

Cloudflare Pages

进入项目 → Settings → Environment variables
添加变量
选择环境（Production / Preview）
重新部署

Railway

选择服务 → Variables
添加变量
自动重新部署

Fly.io

# 设置环境变量
flyctl secrets set API_KEY=your_secret

# 查看
flyctl secrets list

# 删除
flyctl secrets unset API_KEY

常见环境变量

数据库连接

DATABASE_URL=postgresql://user:password@host:5432/dbname
REDIS_URL=redis://host:6379

API 密钥

OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=SG...

应用配置

NODE_ENV=production
PORT=3000
APP_URL=https://example.com

第三方服务

# Google OAuth
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# AWS
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

环境变量文件

.env

默认环境变量，所有环境都加载：

# .env
APP_NAME=MyApp

.env.local

本地开发，覆盖 .env：

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb

.env.production

生产环境：

# .env.production
DATABASE_URL=postgresql://prod-host:5432/mydb

.env.development

开发环境：

# .env.development
DATABASE_URL=postgresql://localhost:5432/mydb

加载顺序

Next.js 加载顺序（优先级从高到低）：

.env.local
.env.production 或 .env.development
.env

验证环境变量

启动时检查

// lib/env.js
const requiredEnvVars = [
  'DATABASE_URL',
  'API_KEY',
]

requiredEnvVars.forEach((envVar) => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`)
  }
})

使用 Zod 验证

import { z } from 'zod'

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  PORT: z.string().transform(Number).pipe(z.number().min(1000)),
})

export const env = envSchema.parse(process.env)

安全最佳实践

1. 不要提交密钥到 Git

# .gitignore
.env.local
.env*.local

2. 使用不同的密钥

开发和生产使用不同的 API 密钥。

3. 定期轮换密钥

定期更换生产环境的密钥。

4. 最小权限原则

API 密钥只给必要的权限。

5. 监控密钥使用

使用服务商的监控功能，发现异常使用。

团队协作

共享环境变量

不要通过聊天工具发送密钥，使用：

1Password / Bitwarden（密码管理器）
Doppler / Infisical（环境变量管理）
团队文档（加密存储）

.env.example

提供模板，不包含实际值：

# .env.example
DATABASE_URL=postgresql://user:password@host:5432/dbname
API_KEY=your_api_key_here
NEXT_PUBLIC_API_URL=https://api.example.com

团队成员复制为 .env.local 并填入实际值。

常见问题

环境变量不生效

检查变量名是否正确
前端变量是否加了前缀（NEXT_PUBLIC_）
修改后是否重启了服务器
托管平台是否重新部署

如何在浏览器中使用

只能使用带前缀的变量：

// ✅ 可以
const apiUrl = process.env.NEXT_PUBLIC_API_URL

// ❌ 不可以（返回 undefined）
const apiKey = process.env.API_KEY

如何在 Docker 中使用

# Dockerfile
FROM node:18
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

# 运行时注入环境变量
CMD ["npm", "start"]

# 运行时传入
docker run -e DATABASE_URL=postgresql://... myapp

环境变量配置

目录