Tanstack React Query 导入失败求助（Next.js 14）

核心原因分析 #

这类批量导入错误几乎都是依赖版本不兼容或依赖安装/缓存异常导致的，尤其是@tanstack/react-query与其核心依赖@tanstack/query-core版本不匹配时，会出现大量导出缺失的报错。

具体解决步骤 #

1. 彻底清理依赖残留 #

先移除现有依赖和锁文件，消除版本冲突隐患：

# 删除node_modules文件夹
rm -rf node_modules

# 根据包管理器删除对应锁文件
rm package-lock.json # npm 用户
rm yarn.lock # yarn 用户
rm pnpm-lock.yaml # pnpm 用户

2. 重新安装匹配版本的依赖 #

确保@tanstack/react-query和@tanstack/query-core版本完全一致，直接安装指定版本：

# npm
npm install @tanstack/react-query@5.17.7

# yarn
yarn add @tanstack/react-query@5.17.7

# pnpm
pnpm add @tanstack/react-query@5.17.7

安装完成后，检查package.json中@tanstack/query-core的版本是否和react-query完全一致（v5版本的react-query会自动关联对应版本的query-core）。

3. 配置Next.js转译依赖 #

如果项目的next.config.js有特殊编译配置，需将@tanstack/react-query和@tanstack/query-core加入转译列表：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@tanstack/react-query', '@tanstack/query-core'],
}

module.exports = nextConfig

这一步避免Next.js的模块编译策略导致依赖导出异常。

4. 清除Next.js缓存 #

Next.js的缓存可能残留旧模块，执行清理：

# 直接删除缓存文件夹
rm -rf .next

# 或者通过构建命令清理
npm run build --clean # npm 用户
yarn build --clean # yarn 用户

5. 验证Provider代码（可选优化） #

你的TanstackProvider.tsx代码本身无错误，若后续需使用服务端渲染 hydration 功能，v5版本可补充默认配置，但当前报错与该部分无关：

"use client";

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

const TanstackProvider = ({ children }: { children: React.ReactNode }) => {
  const [queryClient] = useState(() => 
    new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 60 * 1000, // 可选，添加默认缓存策略
        },
      },
    })
  );

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
};

export default TanstackProvider;

额外排查点 #

• 用npm ls @tanstack/query-core（或对应包管理器命令）查看依赖树，排查是否有其他依赖间接引入了不同版本的@tanstack/query-core。
• 确保项目TypeScript版本在4.8以上，与v5版本的@tanstack/react-query兼容。

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