NextJS项目Jest+MSW测试API时Node环境fetch未定义问题排查

核心原因 #

MSW在Node环境下不会自动注入fetch polyfill——只有当Node环境本身提供全局fetch（Node 18+内置），或者你手动配置了polyfill，MSW才能正常拦截fetch请求。如果你的Node版本低于18，就会触发这个错误。

具体解决步骤 #

• 第一步：确认Node版本
  打开终端执行node -v，如果版本低于18.x，直接升级到18+（推荐方案），Node 18及以上版本已经内置全局fetch，无需额外配置。

• 第二步：正确配置MSW Node端服务
  确保测试文件使用MSW的Node端API，而非浏览器端的Worker：

  // 测试文件开头
  import { setupServer } from 'msw/node'
  import { rest } from 'msw'
  
  // 定义请求处理器
  const server = setupServer(
    rest.get('/api/data', (req, res, ctx) => {
      return res(ctx.json({ mockData: 'test' }))
    })
  )
  
  // 所有测试前启动服务器
  beforeAll(() => server.listen())
  // 单个测试后重置请求处理器
  afterEach(() => server.resetHandlers())
  // 所有测试后关闭服务器
  afterAll(() => server.close())
  

• 第三步：低版本Node添加fetch polyfill（可选）
  若无法升级Node版本，安装cross-fetch作为polyfill：

  1. 安装依赖：

     npm install cross-fetch --save-dev
     

  2. 在Jest全局设置文件（如jest.setup.js）中导入：

     import 'cross-fetch/polyfill'
     

  3. 确保jest.config.js中配置了该setup文件：

     module.exports = {
       setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
     }
     

• 第四步：检查NextJS的Jest测试环境
  根据测试对象调整Jest环境配置：

  • 测试客户端组件：使用jsdom环境（NextJS默认配置），jsdom本身提供fetch支持。
  • 测试服务器端代码：使用node环境，此时必须保证Node版本≥18或已添加polyfill。

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