如何在Jest+TypeScript项目中正确配置使用node-fetch v3

报错核心是Jest默认运行在CommonJS模式下，无法直接解析node-fetch v3及以上版本的纯ESModule格式代码，按以下步骤调整配置即可正常使用。

1. 调整package.json #

• 在配置最外层增加"type": "module"，声明项目默认遵循ESModule规范
• 修改test启动脚本，开启Node的ESM模块支持：

"scripts": {
  "build": "tsc",
  "test": "NODE_OPTIONS=--experimental-vm-modules jest"
}

Windows环境如果出现环境变量识别错误，可安装cross-env依赖，将test命令替换为cross-env NODE_OPTIONS=--experimental-vm-modules jest实现跨平台兼容

2. 调整tsconfig.json #

修改compilerOptions下的模块相关配置，适配Node原生ESM解析规则，核心配置参考：

{
  "include": ["./src/**/*", "./test/**/*"],
  "exclude": ["node_modules"],
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./out",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

必须调整的配置项说明：

• 原target设为ES5版本过低，ESM特性最低需要ES2020及以上目标版本支持
• module和moduleResolution统一设为NodeNext，匹配Node.js原生ESM的路径解析逻辑
• 原include配置仅覆盖src目录，需要补充test目录，避免测试文件不被TypeScript识别
• rootDir调整为项目根目录，兼容src、test双目录的项目结构

3. 调整jest.config.js #

将Jest配置切换为ESM模式，同时开启node_modules下ESM依赖的转译支持，配置参考：

/** @type {import('jest').Config} */
const config = {
  preset: 'ts-jest/presets/default-esm',
  testEnvironment: 'node',
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapper: {
    '^(\\.{1,2}/.*)\\.js$': '$1',
  },
  transform: {
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        useESM: true,
      },
    ],
  },
  transformIgnorePatterns: []
};

export default config;

关键配置说明：

• preset替换为ts-jest的ESM专用预设，弃用默认的CommonJS预设
• 通过extensionsToTreatAsEsm声明.ts后缀文件按ESM模块处理
• moduleNameMapper用于匹配TypeScript编译后自动追加.js后缀的导入路径
• transformIgnorePatterns设为空数组，强制Jest转译node_modules下的ESM依赖（默认Jest会跳过node_modules下的文件转译，是触发原报错的核心原因之一）
• 配置文件本身使用export default语法导出，匹配ESM规范

可选简化方案 #

如果使用Node.js 18及以上版本，可直接使用Node内置的全局fetch API，无需额外安装node-fetch依赖，只要将tsconfig的target调整为ES2022及以上，即可直接在业务代码和测试代码中调用fetch，省去所有ESM适配配置。

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