
本文详解 TanStack React Query(v5+)在 Next.js 14 App Router 中因包版本不匹配、SSR/客户端混合使用导致的 hydrate is not exported 等导入失败问题,并提供兼容 v5 的正确服务端渲染(SSR)配置与 Provider 实现。
本文详解 tanstack react query(v5+)在 next.js 14 app router 中因包版本不匹配、ssr/客户端混合使用导致的 `hydrate is not exported` 等导入失败问题,并提供兼容 v5 的正确服务端渲染(ssr)配置与 provider 实现。
你遇到的错误——如 Attempted import error: 'hydrate' is not exported from '@tanstack/query-core'——根本原因并非代码写错,而是版本不兼容 + SSR 配置缺失。尤其当你使用 Next.js 14(App Router)时,React Query v5 已彻底移除 hydrate 函数,并改用全新的 HydrationBoundary 组件(注意:不是 Hydrate!),同时要求 @tanstack/query-core 与 @tanstack/react-query 版本严格对齐(必须同为 v5.x)。
✅ 正确配置步骤(Next.js 14 + React Query v5)
1. 确保版本统一且为 v5
运行以下命令清理并安装最新稳定版 v5:
npm uninstall @tanstack/react-query @tanstack/query-core npm install @tanstack/react-query@latest # 自动安装匹配的 @tanstack/query-core(v5.x)
⚠️ 警告:切勿混用 v4 和 v5。v4 的
Hydrate组件在 v5 中已被废弃;v5 使用HydrationBoundary,且其内部依赖的query-coreAPI 已重构。
2. 创建正确的 Client-Side Provider(TanstackProvider.tsx)
由于 Next.js App Router 的 layout.tsx 是服务端组件(Server Component),而 QueryClientProvider 必须在客户端渲染,因此需确保:
使用 assistant-ui 构建具有可重用线程、运行时、消息组件和模型/提供者适配器的生产级 React 聊天界面。
- Provider 文件标记
"use client" - 使用
useState初始化QueryClient(避免服务端重复创建) -
v5 中不再需要手动传递
dehydratedState到根 layout(除非你主动做 SSR 数据预取)
// src/app/_components/providers/TanstackProvider.tsx
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { HydrationBoundary } from "@tanstack/react-query";
import { ReactNode, useState } from "react";
export default function TanstackProvider({ children }: { children: ReactNode }) {
const [queryClient] = useState(() => new QueryClient());
return (
<QueryClientProvider client={queryClient}>
{/* HydrationBoundary 用于包裹需要水合的子组件(如服务端预取的数据) */}
<HydrationBoundary>
{children}
</HydrationBoundary>
</QueryClientProvider>
);
}3. 在 layout.tsx 中正确使用(无需服务端传参)
layout.tsx 本身是 Server Component,但 TanstackProvider 是 Client Component,可直接嵌套使用:
// src/app/layout.tsx
import type { Metadata } from "next";
import { Rubik } from "next/font/google";
import "./globals.css";
import TanstackProvider from "./_components/providers/TanstackProvider";
const rubik = Rubik({ subsets: ["latin"] });
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body className={rubik.className}>
<TanstackProvider>
{children}
</TanstackProvider>
</body>
</html>
);
}4. (可选)启用 SSR 数据预取(如需服务端获取初始数据)
若你想在服务端获取数据并注入到 QueryClient(例如首页评论列表),请在 page.tsx 中使用 getServerSideProps 替代方案(App Router 推荐方式):
// src/app/page.tsx
import { dehydrate, QueryClient } from "@tanstack/react-query";
import { getComments } from "@/lib/helpers/db-calls";
export default async function Home() {
const queryClient = new QueryClient();
// 预取数据并脱水
await queryClient.prefetchQuery({
queryKey: ["comments"],
queryFn: () => getComments(), // 你的服务端函数(如 Prisma 查询)
});
const dehydratedState = dehydrate(queryClient);
return (
<HydrationBoundary state={dehydratedState}>
<div>Home Page with Prefetched Comments</div>
</HydrationBoundary>
);
}? 注意:
HydrationBoundary必须在QueryClientProvider内部使用,且其state属性仅在需要水合的局部区域(如特定页面)才需传入;全局 Provider 中无需设置。
? 关键总结与避坑指南
- ❌ 错误做法:在 v5 中继续使用 v4 的
Hydrate组件或手动导入hydrate函数; - ✅ 正确做法:v5 使用
<hydrationboundary></hydrationboundary>包裹需水合内容,QueryClientProvider提供上下文; - ? 清理缓存:执行
rm -rf node_modules/.cache和npm run dev重启,避免旧构建残留; - ? 检查依赖树:运行
npm ls @tanstack/react-query @tanstack/query-core,确认两者均为5.x.x且无重复安装; - ? 开发提示:首次使用可在
useQuery中添加suspense: false避免意外 Suspense 报错,逐步开启特性。
按以上配置,所有 useQuery、useMutation、useQueries 等 Hook 均可正常导入并工作。问题根源在于版本迁移文档未被充分遵循——v5 不是 v4 的平滑升级,而是架构级演进。严格遵循官方 v5 文档(https://www.php.cn/link/1848dab92ff120ef60f9cda0fe90f540)是成功集成的前提。

















