Next.js13.4 App Router中TanStack Query预取数据(Hydrate/SSR)失效问题

1. 确认组件执行环境 #

HydratedBlogList必须是服务器组件（不能添加'use client'指令），因为prefetchQuery需要在服务器端执行。如果给该组件加了客户端指令，会导致服务器端无法调用相关API，直接抛出"Not implemented"错误。

2. 修正QueryClient初始化逻辑 #

在服务器组件中，需要单独创建QueryClient实例，不能复用客户端的实例。示例代码如下：

// HydratedBlogList.tsx
import { QueryClient, prefetchQuery } from '@tanstack/react-query';
import { getBlogPosts } from '@/lib/api'; // 你的博客数据获取函数

export default async function HydratedBlogList({ page }: { page: number }) {
  const queryClient = new QueryClient();
  
  // 对应报错的第19行，确保queryFn是服务器端可执行的逻辑
  await prefetchQuery({
    queryClient,
    queryKey: ['blogPosts', page],
    queryFn: () => getBlogPosts(page),
  });

  return (
    <div suppressHydrationWarning>
      <BlogList queryClient={queryClient} page={page} />
    </div>
  );
}

3. 排查数据获取函数的兼容性 #

你的getBlogPosts函数如果依赖window、document等浏览器专属API，在服务器预取阶段会直接报错。要确保数据获取逻辑是纯服务器兼容的——比如直接调用后端接口、读取数据库，不要涉及浏览器环境的对象。

4. 检查Providers组件配置 #

Providers必须是客户端组件（添加'use client'），并且正确初始化和传递QueryClient：

// Providers.tsx
'use client';

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

export default function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());

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

5. 验证Hydration流程 #

确保服务器端预取的数据能正确同步到客户端：

• 服务器端完成prefetch后，把QueryClient实例传递给客户端的BlogList组件
• BlogList作为客户端组件，使用useQuery时会自动复用预取的数据，不会重复发起请求

如果以上步骤都排查后仍有问题，建议贴出HydratedBlogList第19行的具体代码，能更精准定位问题。

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