如何在next build阶段执行服务端环境变量验证？

问题场景 #

我有一个服务端环境变量验证文件src/config/server/env.ts，代码如下：

'use server';

import zod from 'zod';

if (typeof window !== 'undefined') {
  throw new Error('env should not be imported on the frontend!');
}

const schema = zod.object({
  API_KEY: zod.string({
    message: "API_KEY must be a string"
  }).min(1, "API_KEY must be at least 1 character long"),
});

export const env = schema.parse(process.env);

该文件在src/utils/api.ts中被导入使用，代码如下：

'use server';

import { env } from '@config/server/env';

const api = new API({
  key: env.API_KEY,
});

export default api;

这些代码用于src/api/目录下，但执行next build命令时，服务端环境变量验证并未触发；而类似的客户端环境变量验证因参与构建编译可正常触发。

解决方案 #

方法1：在next.config.js中触发验证

Next.js执行next build时会加载next.config.js，因此可以在这里导入验证逻辑并触发执行，验证失败会直接中断构建：

// next.config.js
// 项目使用CommonJS的话，请改用require语法
import { env } from './src/config/server/env';

// 导入时schema.parse已自动执行，验证失败会抛出错误终止构建
env;

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

export default nextConfig;

方法2：添加预构建脚本

在package.json中新增prebuild脚本，让它在next build之前执行环境变量验证：

{
  "scripts": {
    "prebuild": "node -r tsx src/config/server/env.ts",
    "build": "next build"
  }
}

• 依赖准备：需要安装tsx（执行npm install tsx --save-dev），用于直接运行TypeScript文件。
• 执行逻辑：运行npm run build时，prebuild会自动先执行，触发环境变量验证；若验证失败，脚本会抛出错误，终止后续构建流程。

原问题原因 #

服务端代码（如src/api/下的路由文件）在next build阶段仅会被编译，不会被执行，因此schema.parse不会触发；而客户端代码会被打包进前端bundle，在构建或运行时会执行验证逻辑，所以能正常触发。

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