Kenhuang Academy
  • English

      • Next.js Environment Variables

      Overview

      Environment variables store configuration such as API keys and database connections. Next.js provides robust environment variable support.

      Basic Usage

      Creating Environment Files

      # .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"

      Using Environment Variables

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

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

      Environment File Priority

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

      Client-Side Variables

      NEXT_PUBLIC_ Prefix

      # .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>
}

      Runtime Configuration

      next.config.js

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

      Type Safety

      Defining Types

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

      Validating Environment Variables

      // 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)

      Best Practices

      1. Do Not Commit Sensitive Information

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

      2. Provide an Example File

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

      3. Documentation

      # 环境变量说明

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

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

      4. Validate on Startup

      // 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()

      Previous Chapter: Next.js Custom Server | Next Chapter: Next.js Monitoring and Analytics