迁移@tanstack/react-query至v5后Jest测试报QueryClient构造函数错误

常见原因及修复步骤 #

• 确认依赖版本与安装状态
  确保已完全移除旧版react-query，并正确安装v5版本的@tanstack/react-query：

  npm uninstall react-query @tanstack/react-query
  npm install @tanstack/react-query@latest
  

  检查package.json，确保仅存在@tanstack/react-query依赖，无旧版react-query残留。

• 调整Jest模块解析配置
  Jest可能未正确解析v5包，需检查jest.config.js：

  • 若使用moduleNameMapper，添加对应映射确保加载正确的文件：

    moduleNameMapper: {
      '^@tanstack/react-query$': '@tanstack/react-query/dist/react-query.development.js',
    },
    

  • 检查transformIgnorePatterns，确保未排除@tanstack/react-query（若有排除项需移除）：

    transformIgnorePatterns: [
      // 删除包含@tanstack/react-query的排除规则
    ],
    

• 清理缓存并重启测试进程
  模块缓存可能导致旧版本代码残留，执行以下操作：

  • 删除项目根目录的node_modules/.cache文件夹（若使用Webpack/Vite）
  • 重启Jest测试服务，确保模块重新加载

• 检查测试文件的导入一致性
  确认测试文件中QueryClient和QueryClientProvider的导入与业务代码一致，均来自@tanstack/react-query：

  import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
  

额外排查方向 #

• 若使用Monorepo，确保所有子包均升级至React Query v5，避免跨包版本冲突
• 执行npm ls react-query查看依赖树，排查是否有第三方库依赖旧版react-query

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