Next.js 环境变量 🔧

🎯 概述

环境变量用于存储配置信息，如 API 密钥、数据库连接等，Next.js 提供了强大的环境变量支持。

📦 基本用法

创建环境文件

# .env.local (本地开发，不提交到 Git)
DATABASE_URL="postgresql://localhost:5432/mydb"
JWT_SECRET="your-secret-key"

# .env.production (生产环境)
DATABASE_URL="postgresql://prod-server:5432/mydb"

# .env (所有环境)
NEXT_PUBLIC_API_URL="https://api.example.com"

使用环境变量

// 服务端
const dbUrl = process.env.DATABASE_URL
const secret = process.env.JWT_SECRET

// 客户端 (必须以 NEXT_PUBLIC_ 开头)
const apiUrl = process.env.NEXT_PUBLIC_API_URL

🚀 环境文件优先级

.env.local          # 最高优先级
.env.production     # 生产环境
.env.development    # 开发环境
.env                # 默认

📝 客户端变量

NEXT_PUBLIC_ 前缀

# .env.local
NEXT_PUBLIC_API_URL="https://api.example.com"
NEXT_PUBLIC_GA_ID="G-XXXXXXXXXX"

// 可以在客户端组件中使用
'use client'

export default function Component() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL
  return <div>{apiUrl}</div>
}

🎨 运行时配置

next.config.js

module.exports = {
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
  publicRuntimeConfig: {
    apiUrl: process.env.API_URL,
  },
  serverRuntimeConfig: {
    secret: process.env.SECRET,
  },
}

📊 类型安全

定义类型

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL: string
    JWT_SECRET: string
    NEXT_PUBLIC_API_URL: string
  }
}

验证环境变量

// lib/env.ts
import { z } from 'zod'

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  NEXT_PUBLIC_API_URL: z.string().url(),
})

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

📚 最佳实践

1. 不要提交敏感信息

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

2. 提供示例文件

# .env.example
DATABASE_URL="postgresql://localhost:5432/mydb"
JWT_SECRET="your-secret-key-here"
NEXT_PUBLIC_API_URL="https://api.example.com"

3. 文档化

# 环境变量说明

## 必需变量
- `DATABASE_URL`: 数据库连接字符串
- `JWT_SECRET`: JWT 签名密钥 (至少 32 字符)

## 可选变量
- `NEXT_PUBLIC_API_URL`: API 基础 URL (默认: http://localhost:3000)

4. 验证启动时

// lib/validate-env.ts
function validateEnv() {
  const required = ['DATABASE_URL', 'JWT_SECRET']
  
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing required environment variable: ${key}`)
    }
  }
}

validateEnv()

🔗 相关资源

• Next.js 环境变量文档

---

下一步：学习 Next.js 监控和分析。