如何在Jest单元测试中覆盖Next.js+React组件的ENV变量默认值？

核心原理 #

组件在导入阶段就会读取process.env的值，所以必须先修改环境变量，再导入组件，不能反过来。另外，用require导入默认导出的组件时，要通过.default获取正确的组件引用。

方案一：单测试文件内动态设置环境变量 #

直接在测试文件开头先覆盖process.env，再导入组件：

// 先设置环境变量
process.env.SITE_BRAND = "自定义品牌名";

// 再导入组件（ES模块方式）
import BrandComponent from "../components/BrandComponent";

describe("BrandComponent", () => {
  it("显示自定义品牌名称", () => {
    render(<BrandComponent />);
    expect(screen.getByText("自定义品牌名")).toBeInTheDocument();
  });

  it("使用默认品牌名（未设置时）", () => {
    // 重置环境变量
    delete process.env.SITE_BRAND;
    // 清除模块缓存，避免复用之前导入的组件
    jest.resetModules();
    // 通过require重新导入，注意取.default获取默认导出
    const BrandComponent = require("../components/BrandComponent").default;
    
    render(<BrandComponent />);
    expect(screen.getByText("brand")).toBeInTheDocument();
  });
});

方案二：全局Jest配置预设环境变量 #

如果多个测试文件都需要相同的环境变量，可以在Jest配置文件中全局设置：

// jest.config.js
const nextJest = require("next/jest");

const createJestConfig = nextJest({
  dir: "./",
});

const customJestConfig = {
  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
  // 其他Jest配置项...
};

module.exports = async () => {
  const jestConfig = await createJestConfig(customJestConfig)();
  // 全局注入环境变量
  jestConfig.globalSetup = () => {
    process.env.SITE_BRAND = "全局默认品牌";
  };
  return jestConfig;
};

或者直接在jest.setup.js中设置：

// jest.setup.js
process.env.SITE_BRAND = "全局品牌名";

方案三：复用Next.js的环境变量逻辑 #

Next.js支持通过.env文件管理变量，测试时可以加载专属的测试环境配置：

1. 在项目根目录创建.env.test文件：

SITE_BRAND=测试环境品牌

2. 修改jest.config.js，让Jest加载测试环境的env文件：

// jest.config.js
const nextJest = require("next/jest");
const dotenv = require("dotenv");

dotenv.config({ path: ".env.test" });

const createJestConfig = nextJest({
  dir: "./",
});

const customJestConfig = {
  // 其他Jest配置项...
};

module.exports = createJestConfig(customJestConfig);

常见问题修复 #

• 「Element type is invalid」错误：用require导入默认导出的组件时，必须加上.default属性，因为ES模块的默认导出会被包裹在require返回对象的default字段中。
• 环境变量不生效：确保修改process.env的代码在组件导入之前执行，组件一旦导入就会缓存初始的env值，后续修改需要用jest.resetModules()清除缓存后重新导入。

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