Next.js无服务器函数间共享React Query QueryClient是否可行？

1. 服务端共享QueryClient是否为反模式？ #

全局单例QueryClient是反模式，但单请求内共享完全合理：

• 如果你把prefetchQueryClient定义成全局常量，会导致服务端多请求并发时，缓存被不同用户的请求共享，轻则数据不一致，重则出现用户数据泄露风险，绝对不能这么做。
• 但如果是在单个请求的生命周期内共享QueryClient（比如同一个getServerSideProps调用、同一个Server Component渲染流程里），这是React Query官方推荐的服务端预取方式，能有效复用同一请求内的Prismic数据请求，避免重复调用。

2. 合理的服务端缓存实现 #

Pages Router 方案 #

封装公共预取逻辑，每个请求创建独立的QueryClient，同一请求内复用缓存：

// 公共预取工具函数
async function prefetchPrismicAssets(queryClient) {
  // 预取页眉，设置1小时缓存过期
  await queryClient.prefetchQuery({
    queryKey: ['prismic-header'],
    queryFn: () => fetchPrismicDocument('header'),
    staleTime: 3600000,
  });
  // 预取页脚
  await queryClient.prefetchQuery({
    queryKey: ['prismic-footer'],
    queryFn: () => fetchPrismicDocument('footer'),
    staleTime: 3600000,
  });
}

// 页面的getServerSideProps
export async function getServerSideProps() {
  const queryClient = new QueryClient();
  await prefetchPrismicAssets(queryClient);

  return {
    props: {
      dehydratedState: dehydrate(queryClient), // 序列化缓存传给客户端水合
    },
  };
}

每个请求都会生成独立的QueryClient，既保证了请求隔离，又能在同一请求内避免重复调用Prismic API。

App Router 方案 #

利用React Query的实验性Next.js集成，自动绑定请求上下文，同一请求内的Server Components自动共享QueryClient：

import { createServerComponentClient } from '@tanstack/react-query-next-experimental';
import { cookies } from 'next/headers';

// 封装Prismic数据获取函数
async function getPrismicHeader() {
  const queryClient = createServerComponentClient({ cookies });
  return queryClient.fetchQuery({
    queryKey: ['prismic-header'],
    queryFn: () => fetchPrismicDocument('header'),
    staleTime: 3600000,
  });
}

// 布局组件（Server Component）
export default async function RootLayout({ children }) {
  const header = await getPrismicHeader();
  const footer = await getPrismicFooter(); // 同一请求内自动复用缓存，只发一次API请求
  return (
    <html>
      <body>
        <Header data={header} />
        {children}
        <Footer data={footer} />
      </body>
    </html>
  );
}

这种方式无需手动管理QueryClient生命周期，Next.js会自动为每个请求创建独立实例，安全又省心。

3. Next/Vercel平台的进阶优化方案 #

除了React Query，结合Next.js和Vercel的原生能力可以进一步降低API调用量：

• 静态生成（SSG）+增量静态再生（ISR）：如果页眉、页脚这类数据更新不频繁，用getStaticProps生成静态页面，同时设置revalidate: 3600让页面每小时自动更新，大部分请求直接命中静态资源，完全跳过Prismic API调用。
• Edge Cache缓存：如果通过代理转发Prismic请求，可以在next.config.js里配置Edge层缓存策略，让Vercel的边缘节点缓存API响应：

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/prismic-proxy', // 你的Prismic代理接口
        headers: [
          {
            key: 'Cache-Control',
            value: 's-maxage=3600, stale-while-revalidate=86400',
          },
        ],
      },
    ];
  },
};

这样边缘节点会缓存API响应1小时，过期后后台自动刷新，进一步减少源站的Prismic调用。

总结 #

• 绝对不要用全局单例QueryClient，这是典型的服务端反模式；但单请求内共享QueryClient是安全且高效的方案。
• 结合React Query的服务端预取+Next.js的SSG/ISR+Vercel Edge Cache，能把Prismic API调用量降到最低，避免因调用过多导致的成本上涨。

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