Next.js构建报错：No QueryClient set，需配置QueryClientProvider

问题根源 #

开发模式下Next.js以客户端渲染为主，组件在浏览器端完成hydration后才会执行React Query hooks，此时QueryClient可能通过局部配置或动态加载生效；但next build执行静态生成（SSG）时，会在构建阶段直接渲染页面组件，若组件使用了React Query hooks却未被QueryClientProvider全局包裹，就会触发No QueryClient set错误。

修复步骤 #

1. 全局配置QueryClientProvider #

在项目的pages/_app.js文件中，全局包裹整个应用，确保所有页面都能访问到QueryClient：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import '../styles/globals.css';

// 创建全局QueryClient实例
const queryClient = new QueryClient({
  // 可选配置：关闭不必要的自动重取，优化生产环境表现
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false,
    },
  },
});

function MyApp({ Component, pageProps }) {
  return (
    <QueryClientProvider client={queryClient}>
      <Component {...pageProps} />
    </QueryClientProvider>
  );
}

export default MyApp;

2. 清理局部重复配置 #

检查GridView、TableView页面或其子组件中是否存在单独的QueryClientProvider，移除重复配置，确保全局Provider是唯一的上下文来源，避免上下文冲突。

3. 适配静态生成场景（可选） #

如果页面使用getStaticProps做静态数据预取，可直接在getStaticProps中获取数据并通过props传递，减少构建阶段对React Query的依赖；若必须在组件内使用React Query，可通过动态导入组件强制仅在客户端渲染：

import dynamic from 'next/dynamic';

// 仅在客户端加载依赖React Query的组件
const DataTable = dynamic(() => import('../components/DataTable'), {
  ssr: false,
});

验证修复 #

执行next build命令确认构建成功，再通过next start启动生产模式，验证页面功能正常。

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