Next14+React Query构建报错：未设置QueryClient，请求技术支持

核心原因 #

Next14 App Router默认组件为服务端组件，而React Query的useQuery等hooks仅能在客户端组件中运行。开发模式下的 hydration 兼容会掩盖问题，但构建时服务端渲染路径中调用这些hooks会直接触发找不到QueryClient的错误。

分步解决方案 #

1. 标记所有使用React Query的组件为客户端组件
   在每个调用useQuery、useMutation或其他React Query hooks的组件顶部添加：

   'use client'
   

   确保服务端渲染时不会执行这些客户端专属逻辑。

2. 正确配置QueryClientProvider的作用域
   如果你的根layout.tsx是服务端组件（默认就是），需要嵌套一个客户端组件来提供QueryClientProvider，避免在服务端实例化QueryClient：

   // app/query-provider.tsx（客户端组件）
   'use client'
   
   import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
   import { useState } from 'react'
   
   export default function QueryProvider({ children }) {
     // 用useState确保QueryClient仅在客户端初始化一次
     const [queryClient] = useState(() => new QueryClient({
       // 可选：添加你的React Query配置
       defaultOptions: {
         queries: {
           staleTime: 5 * 1000,
         },
       },
     }))
   
     return (
       <QueryClientProvider client={queryClient}>
         {children}
       </QueryClientProvider>
     )
   }
   

   然后在根layout中引入：

   // app/layout.tsx（服务端组件）
   import QueryProvider from './query-provider'
   
   export default function RootLayout({ children }) {
     return (
       <html lang="zh-CN">
         <body>
           <QueryProvider>{children}</QueryProvider>
         </body>
       </html>
     )
   }
   

3. 排查服务端逻辑中的违规调用
   检查是否在generateStaticParams、getServerSideProps或其他服务端专属函数中，间接调用了React Query的hooks。这类场景下必须避免使用客户端hooks，改用服务端直接请求数据。

额外检查 #

• 确认@tanstack/react-query版本与Next14兼容（v4/v5均支持，优先推荐v5）
• 确保所有路由页面及组件都被QueryClientProvider包裹，没有遗漏的嵌套路由

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