Node.js健康检查API测试Zod验证失败：环境变量缺失排查

问题场景 #

使用Vitest和Supertest测试Node.js Express应用时，Zod环境变量验证报错，提示HOST、DATABASE_URL、GITHUB_SECRET等必填环境变量未定义。这些变量已配置在.env.development.local中，且开发脚本通过--env-file参数加载，但测试时仍无法读取。

解决方案 #

1. 为测试脚本单独配置环境变量加载 #

Vitest不会自动继承开发脚本的--env-file配置，需在测试脚本中单独指定：
修改package.json的测试命令：

"scripts": {
  "test": "vitest --env-file .env.development.local"
}

如果希望测试环境隔离，建议创建.env.test文件，填入测试专用的环境变量，然后指向该文件：

"scripts": {
  "test": "vitest --env-file .env.test"
}

2. 在Vitest配置中直接定义测试环境变量 #

如果不想维护单独的.env.test文件，可在vitest.config.ts中直接配置测试所需的环境变量：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    env: {
      NODE_ENV: 'test',
      HOST: 'http://localhost',
      DATABASE_URL: 'mongodb://localhost:27017/test-db',
      GITHUB_SECRET: 'test-github-secret',
      PORT: '3000'
    }
  }
});

3. 优化Zod Schema的测试兼容逻辑 #

针对测试环境，可为必填变量添加测试专属默认值，避免验证失败：

const envSchema = z.object({
  HOST: z.string().trim()
    .refine(host => host.startsWith('http') || host.startsWith('https'), 'Invalid URL format')
    .default(process.env.NODE_ENV === 'test' ? 'http://localhost' : undefined),
  DATABASE_URL: z.string().url()
    .trim()
    .refine(url => url.startsWith('mongodb://'), 'Invalid Database URL format')
    .default(process.env.NODE_ENV === 'test' ? 'mongodb://localhost:27017/test-db' : undefined),
  GITHUB_SECRET: z.string().trim().min(1)
    .default(process.env.NODE_ENV === 'test' ? 'test-secret' : undefined),
  // 其他字段保持原有配置
});

或者在safeParse阶段，根据环境补充测试变量：

const testEnvOverrides = process.env.NODE_ENV === 'test' ? {
  HOST: 'http://localhost',
  DATABASE_URL: 'mongodb://localhost:27017/test-db',
  GITHUB_SECRET: 'test-secret'
} : {};

const envServer = envSchema.safeParse({
  ...process.env,
  ...testEnvOverrides
});

4. 通过Vitest Setup文件手动加载环境变量 #

如果使用dotenv包，可创建vitest.setup.ts文件手动加载.env文件：

import dotenv from 'dotenv';
// 根据环境加载对应文件
dotenv.config({ 
  path: process.env.NODE_ENV === 'test' ? '.env.test' : '.env.development.local' 
});

然后在vitest.config.ts中配置加载该setup文件：

export default defineConfig({
  test: {
    setupFiles: ['./vitest.setup.ts']
  }
});

关键原因说明 #

测试运行时的上下文与开发服务器独立，即使开发脚本配置了--env-file，Vitest不会自动复用该配置。同时，测试环境应尽量与生产/开发环境隔离，使用专属配置能避免测试结果受外部环境影响。

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