Next.js项目启动时如何检查必填环境变量是否已定义？

这个需求完全可以实现，下面是几种靠谱的实现方式和相关最佳实践：

一、直接实现启动时校验 #

1. 自定义前置校验脚本 #

在项目根目录写一个简单的Node.js脚本，专门用来校验必填环境变量，然后修改package.json的启动命令，让脚本先执行，校验不通过就终止进程并抛出错误。

比如创建check-env.js：

const requiredEnvVars = ['DATABASE_URL', 'NEXT_PUBLIC_API_URL']; // 替换成你的必填变量

const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);

if (missingVars.length > 0) {
  console.error(`Error: 以下环境变量未定义或为空: ${missingVars.join(', ')}`);
  process.exit(1); // 终止进程，阻止Next.js启动
}

然后修改package.json的脚本：

{
  "scripts": {
    "dev": "node check-env.js && next dev",
    "build": "node check-env.js && next build",
    "start": "node check-env.js && next start"
  }
}

这样启动时如果有必填变量缺失，就会直接抛出错误，不会进入Next.js启动流程。

2. 在next.config.js中添加校验逻辑 #

Next.js启动时会优先加载next.config.js，所以可以在这个文件的顶部直接加入校验代码：

// next.config.js
const requiredEnvVars = ['DATABASE_URL'];

const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);
if (missingVars.length) {
  throw new Error(`Error: the ${missingVars.join(', ')} environment variable is empty or undefined`);
}

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 你的配置项
}

module.exports = nextConfig;

这种方式不需要额外的脚本文件，更简洁，校验失败时Next.js启动流程会直接终止并抛出错误。

二、相关最佳实践 #

1. 维护.env.example模板文件 #

在项目根目录创建.env.example，把所有必填和可选的环境变量都列出来，加上注释说明用途：

# 数据库连接地址（必填）
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# 前端API地址（必填）
NEXT_PUBLIC_API_URL=https://api.example.com

# 可选：日志级别
LOG_LEVEL=info

让开发者直接复制这个文件改名为.env.local来配置，避免漏填变量。

2. 用类型安全工具做更严谨的校验 #

比如使用zod库来定义环境变量的Schema，既可以校验必填项，还能校验变量类型，同时给代码提供类型提示。

先安装zod：

npm install zod

然后创建lib/env.ts：

import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(), // 不仅必填，还校验是否是合法URL
  NEXT_PUBLIC_API_URL: z.string().url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'), // 可选，有默认值
});

// 解析环境变量，失败则抛出错误
export const env = envSchema.parse(process.env);

然后在next.config.js里导入这个文件，启动时就会自动校验：

// next.config.js
require('./lib/env'); // 导入就会触发校验

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 你的配置
}

module.exports = nextConfig;

这种方式不仅在启动时校验，在代码里使用env.DATABASE_URL时还能获得类型提示，避免拼写错误和类型不匹配的问题。

内容的提问来源于stack exchange，提问作者foolo