TanStack Query在Next.js中预取查询的客户端缓存更新问题分析

问题背景

在使用TanStack Query(原React Query)与Next.js集成的过程中，开发者发现了一个关于预取查询(prefetched queries)和客户端缓存更新的问题。具体表现为：当服务器端预取的查询未被await时，客户端缓存无法正确更新，而如果预取查询被await则能正常工作。

核心问题

在Next.js应用中，通过HydrationBoundary将服务器端预取的查询状态传递给客户端时，如果预取查询是以Promise形式传递(未被await)，那么当服务器内容重新获取时，客户端查询缓存不会自动更新。而如果预取查询是被await后传递(即传递的是已解析的数据)，则客户端缓存能够正确更新。

技术细节分析

1. 预取查询的两种传递方式：

   • 直接传递Promise对象(未被await)：服务器组件渲染时不会等待查询完成，而是将Promise序列化后传递给客户端
   • 传递已解析数据(被await)：服务器组件会等待查询完成后再渲染，传递的是完整数据

2. 问题表现：

   • 初始页面加载时，两种方式都能正常工作
   • 当触发服务器动作(如revalidatePath)导致预取组件重新获取数据时
     • 对于未被await的Promise方式，客户端缓存不会更新
     • 对于已await的数据方式，客户端缓存能正确更新

3. 预期行为：

   • 无论预取查询是否被await，当服务器触发重新获取时，新的Promise解析后都应该更新客户端查询缓存

解决方案探讨

从技术实现角度看，这个问题可能源于TanStack Query在客户端处理序列化Promise时的逻辑。当Promise被序列化传递时，客户端可能没有正确建立与服务器端重新获取操作的关联机制。

目前TanStack Query团队已经注意到这个问题，并有相关的PR正在处理这类服务器端渲染与客户端缓存同步的问题。开发者可以关注后续版本更新，或者暂时采用await预取查询的方式作为临时解决方案。

最佳实践建议

在问题修复前，建议开发者在Next.js中使用TanStack Query时：

1. 对于关键数据，优先使用await确保预取查询完成后再渲染
2. 对于非关键数据或需要流式渲染的场景，可以接受初始使用Promise方式，但要注意后续更新可能需要手动处理
3. 密切关注TanStack Query的版本更新，特别是与Next.js集成的改进

这个问题反映了现代前端框架中服务器组件与客户端状态管理之间复杂的交互关系，理解这些底层机制有助于开发者构建更健壮的应用。