Next.js如何动态切换环境配置文件？

Question

在使用 Next.js 开发多环境应用时，如何根据部署环境（如开发、测试、生产）动态加载不同的配置文件（如 `.env.development`、`.env.staging`、`.env.production`），同时避免敏感信息泄露，并确保构建时正确注入环境变量？常见的痛点包括：环境变量未生效、构建时报错“ReferenceError: process is not defined”、动态切换失败导致配置混淆等。如何通过 `next.config.js` 或运行时逻辑实现灵活且安全的环境配置管理？

Answer 1

1. 理解 Next.js 的环境变量机制

Next.js 提供了基于 .env.local、.env.development、.env.staging 和 .env.production 文件的环境变量加载机制。这些文件会根据当前运行模式（NODE_ENV）自动加载对应配置。

• .env.development：开发环境使用，由 next dev 加载
• .env.production：生产构建和运行时使用，由 next build 和 next start 加载
• .env.staging：测试/预发布环境专用，需通过自定义脚本或 CI/CD 显式指定

注意：所有环境变量必须以 NEXT_PUBLIC_ 前缀暴露给前端代码，否则仅在服务端可用，防止敏感信息泄露。

2. 常见痛点分析与根源定位

问题现象	可能原因	影响范围
环境变量未生效	缺少 NEXT_PUBLIC_ 前缀或文件命名错误	客户端无法读取配置
ReferenceError: process is not defined	直接引用 process.env 而未通过 Webpack 注入	浏览器运行时报错
构建时配置混淆	CI/CD 中未正确设置 NODE_ENV	部署环境错误调用开发配置
敏感信息泄露	将数据库密钥等写入带 NEXT_PUBLIC_ 的变量	安全风险

3. 标准环境变量加载流程图

graph TD
    A[启动命令] --> B{判断 NODE_ENV}
    B -->|development| C[加载 .env.development]
    B -->|production| D[加载 .env.production]
    B -->|staging| E[加载 .env.staging]
    C --> F[合并 .env.local]
    D --> F
    E --> F
    F --> G[注入 Webpack DefinePlugin]
    G --> H[构建时替换为字面量]

4. 利用 next.config.js 实现动态配置注入

通过 next.config.js 可以在构建阶段动态读取环境并注入自定义逻辑：

const fs = require('fs');
const path = require('path');

module.exports = (phase, { defaultConfig }) => {
  const env = process.env.NODE_ENV || 'development';
  const envPath = path.resolve(process.cwd(), `.env.${env}`);

  let envConfig = {};
  if (fs.existsSync(envPath)) {
    const dotenv = require('dotenv');
    envConfig = dotenv.parse(fs.readFileSync(envPath));
  }

  return {
    env: {
      ...envConfig,
      // 强制只暴露必要变量
      NEXT_PUBLIC_API_BASE: envConfig.NEXT_PUBLIC_API_BASE,
      NODE_ENV: env,
    },
    webpack(config) {
      config.plugins.push(
        new require('webpack').DefinePlugin({
          'process.env.RUNTIME_ENV': JSON.stringify(env),
        })
      );
      return config;
    },
  };
};

5. 运行时环境判断与配置路由策略

对于需要在客户端动态切换 API 地址的场景，可通过运行时逻辑实现：

// lib/config.js
const CONFIG_MAP = {
  development: {
    apiBase: 'https://dev-api.example.com',
    debug: true,
  },
  staging: {
    apiBase: 'https://staging-api.example.com',
    debug: false,
  },
  production: {
    apiBase: 'https://api.example.com',
    debug: false,
  },
};

export function getConfig() {
  // 使用构建时注入的环境标识
  return CONFIG_MAP[process.env.NODE_ENV] || CONFIG_MAP.development;
}

6. 构建脚本与 CI/CD 集成最佳实践

确保不同环境执行正确的构建命令：

# package.json scripts
"scripts": {
  "dev": "next dev",
  "build:dev": "NODE_ENV=development next build",
  "build:staging": "NODE_ENV=staging next build",
  "build:prod": "NODE_ENV=production next build",
  "start": "next start"
}

在 CI/CD 流程中（如 GitHub Actions），应明确设置环境变量：

# .github/workflows/deploy.yml
- name: Build for Staging
  run: npm run build:staging
  env:
    NODE_ENV: staging

7. 安全性强化措施

• 禁止将 NEXT_PUBLIC_ 用于数据库密码、JWT 密钥等敏感数据
• 使用 dotenv-safe 验证必需变量是否存在
• 在 .gitignore 中排除 .env.local 和具体值文件
• CI/CD 中通过 secrets 注入生产环境变量，而非明文提交
• 定期审计 next.config.js 中的变量暴露逻辑
• 启用 ESLint 插件 eslint-plugin-no-secrets 防止误提交
• 使用 process.browser 判断运行上下文避免 SSR 错误
• 对非公开变量使用 getServerSideProps 动态注入
• 采用 runtimeConfig 模式分离公共与私有配置
• 日志中脱敏输出环境变量内容