升级node-fetch@3.0.0后Jest运行报Cannot use import statement outside a module错误

核心问题原因 #

node-fetch 3.0及以上版本为纯ESM模块，而Jest默认仅处理项目源码的转译，会跳过node_modules下的ESM模块解析，同时CJS格式的jest.requireActual无法正确读取ESM模块的导出内容，就会出现你遇到的两类报错。

可选解决方案 #

方案1：降级兼容（改动最小，优先推荐） #

如果没有强制使用node-fetch 3.x新特性的需求，直接降级到2.x版本即可，2.x版本同时兼容CJS和ESM，原有代码无需修改：

npm install node-fetch@2
# 若使用TypeScript，同步安装对应类型包
npm install @types/node-fetch@2 -D

原有jest.requireActual("node-fetch")的写法可直接正常运行。

方案2：保留node-fetch 3.x，调整Jest配置适配ESM #

步骤1：修改项目基础配置

在package.json中新增配置，声明项目为ESM模块：

{
  "type": "module"
}

调整tsconfig.json编译配置，适配ESM规范：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "NodeNext"
  }
}

步骤2：修改Jest配置

保留ts-jest转译规则，新增ESM兼容配置，同时放开对node-fetch及其依赖的转译忽略：

// jest.config.js
export default {
  transform: {
    "^.+\\.ts?$": ["ts-jest", { useESM: true }]
  },
  // 放开对node-fetch及其依赖包的转译限制
  transformIgnorePatterns: [
    "node_modules/(?!(node-fetch|data-uri-to-buffer|fetch-blob|formdata-polyfill)/)"
  ],
  moduleFileExtensions: ["ts", "js", "mjs", "cjs", "json", "node"],
  // 声明.ts文件按ESM处理
  extensionsToTreatAsEsm: [".ts"]
}

步骤3：保持已修改的test脚本

你之前调整的test脚本无需改动：

{
  "scripts": {
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
  }
}

原有导入Response的import { Response } from "node-fetch"写法可正常运行。

方案3：使用兼容封装包替代 #

无需修改现有配置，直接替换依赖为兼容CJS/ESM的cross-fetch即可，API和node-fetch完全一致：

npm install cross-fetch

导入代码调整为：

import { Response } from "cross-fetch";

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