Next.js 14+Server Actions+React Query 5：如何在generateMetadata中处理查询？

你的方案整体方向符合 Next.js App Router 结合 TanStack Query SSR 的最佳实践，但有两个细节需要优化：

1. QueryClient 实例不能放在模块顶部
   你现在在模块级声明 queryClient，这会导致跨请求缓存污染——模块级变量是所有请求共享的，不同用户的查询数据会混在一起。正确的做法是在 generateMetadata 和 Page 函数内部各自创建实例：

   export async function generateMetadata(): Promise<Metadata> {
     const queryClient = getQueryClient(); // 每个请求独立创建
     const data = await queryClient.fetchQuery({
       queryKey: ['orders', params],
       queryFn: () => getOrders(params),
     });
     return { title: "title" + data.size };
   }
   
   export default async function Page() {
     const queryClient = getQueryClient(); // 每个请求独立创建
     await queryClient.prefetchQuery({
       queryKey: ['orders', params],
       queryFn: () => getOrders(params),
     });
     // ... 后续组件渲染代码
   }
   

2. 避免重复 API 请求
   generateMetadata 和 Page 是独立执行的两个函数，各自的 QueryClient 缓存不共享，所以当前代码会触发两次 getOrders 调用。解决方式分两种场景：

   • 如果请求是无用户专属数据的公共接口：Next.js 内置的 fetch 默认会缓存请求结果，两次调用实际只会发一次 API 请求，无需额外处理。
   • 如果请求包含用户专属数据（比如 accessToken 是每个用户独有的）：可以给 fetch 加上 cache: 'force-cache' 让 Next.js 按请求参数/headers 生成缓存键，或者在服务器端用 LRU 缓存封装 getOrders，避免重复调用接口。

两者的缓存机制是独立的，但可以配合工作：

• Next.js fetch 缓存：这是服务器/CDN 级别的缓存，静态渲染时默认永久缓存，动态渲染时默认缓存到 CDN。你可以通过 fetch 的 cache 参数（比如 no-store、reload）或 revalidate 字段调整缓存策略。当 React Query 的 queryFn 调用 fetch 时，会优先使用这个缓存，只要缓存没过期就不会发新请求。
• React Query 缓存：这是客户端的内存/持久化缓存，服务器端的 QueryClient 是每个请求独立的，不会跨请求共享；客户端会通过 dehydrate 和 HydrationBoundary 恢复服务器端的缓存，之后由 React Query 自己管理缓存的更新、失效。
• 注意点：如果 getOrders 里的 accessToken 是用户专属的，Next.js 会把不同 token 的请求当成不同的缓存条目，此时 fetch 缓存不会复用，还是会触发多次请求，需要额外处理。客户端渲染时，React Query 会优先用自己的内存缓存，只有缓存失效时才会调用 queryFn，这时 fetch 的缓存规则依然生效。

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