Next.js中使用QueryClientProvider出现组件传递限制报错咨询

问题原因 #

Next.js 13+ App Router下，默认的RootLayout是服务端组件，而QueryClientProvider是依赖客户端上下文的组件。你直接在服务端组件里创建QueryClient类实例并传给客户端组件，违反了Next.js的规则——服务端组件仅允许传递普通对象、内置类型，不能传递类实例或空原型对象。

解决方案 #

把所有客户端相关的Provider封装成单独的客户端组件，在组件内部创建QueryClient实例，避免跨组件传递类实例：

1. 创建单独的客户端Provider组件
   在app目录下新建providers.tsx：

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { Toaster } from 'react-hot-toast';
import { GoogleOAuthProvider } from '@react-oauth/google';
import type { PropsWithChildren } from 'react';

export default function Providers({ children }: PropsWithChildren) {
  // 在客户端组件内部创建QueryClient实例
  const queryClient = new QueryClient();

  return (
    <QueryClientProvider client={queryClient}>
      <GoogleOAuthProvider clientId="你的Google客户端ID">
        {children}
        <Toaster />
        <ReactQueryDevtools />
      </GoogleOAuthProvider>
    </QueryClientProvider>
  );
}

2. 修改RootLayout，引入封装好的Providers组件
   更新app/layout.tsx：

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import Providers from './providers';

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "X",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

为什么这样有效 #

• 'use client'指令将Providers组件标记为客户端组件，所有内部代码（包括QueryClient实例化）都在客户端执行，不会触发服务端组件的传值限制。
• 服务端组件RootLayout仅负责渲染这个客户端组件，不需要传递任何类实例，完全符合Next.js的组件模型规则。
• 把所有客户端依赖的Provider集中在一处，逻辑更清晰，也便于后续维护。

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