如何修复NextJS14与Jest集成时的无效环境变量错误

问题原因 #

测试环境下Jest未正确加载环境变量，导致Zod对APP_URL和NEXT_PUBLIC_API_BASE_URL的验证失败。正常运行时Next.js会自动加载.env.local，但测试环境需要手动配置变量加载逻辑，尤其是server端变量（如APP_URL）不会在jsdom环境中自动注入。

解决方案 #

1. 创建/完善测试环境变量文件 #

在项目根目录创建.env.test文件，填入与.env.local对应的测试环境变量：

NEXT_PUBLIC_API_BASE_URL="https://api-devstore.vercel.app"
APP_URL="http://localhost:3000"

确保文件路径与jest.config.mjs中setupFiles配置的路径一致。

2. 修正环境变量加载逻辑 #

修改jest.setup.js，确保loadEnvConfig正确加载测试环境变量：

import '@testing-library/jest-dom'
import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
// 第二个参数设为true，强制加载测试环境变量
loadEnvConfig(projectDir, true)

3. 确保Jest配置的文件路径正确 #

检查jest.config.mjs中的路径配置，避免相对路径错误：

const config = {
  setupFiles: ['<rootDir>/.env.test'],
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jest-environment-jsdom',
}

4. Mock服务器组件中的API调用（可选但推荐） #

由于Home是服务器组件，测试时会执行内部API请求，可能触发环境变量依赖或实际网络请求。建议mock相关函数：

import { render, screen } from '@testing-library/react'
import Home from '../src/app/(store)/(home)/page'

// 替换为getFeaturedProducts所在的实际文件路径
jest.mock('../src/utils/api', () => ({
  getFeaturedProducts: async () => [{ name: 'Moletom' }],
}))

describe('Home component', () => {
  test('renders highlighted product', async () => {
    render(<Home />)
    expect(await screen.getByText('Moletom')).toBeInTheDocument()
  })
})

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