TanStack Query在Next.js SSR中实现无限滚动的最佳实践

2025-05-01 20:58:03作者：房伟宁

前言

在使用Next.js的服务器端渲染(SSR)功能时，结合TanStack Query实现无限滚动列表是一个常见的需求。然而，开发者经常会遇到一个棘手问题：当用户在无限滚动列表页面和其他页面之间导航时，列表数据会被重置，导致糟糕的用户体验。本文将深入分析这个问题，并提供几种有效的解决方案。

问题分析

在典型的实现中，开发者会在服务器组件中使用prefetchInfiniteQuery预取数据，然后在客户端组件中使用useSuspenseInfiniteQuery实现无限滚动。但当用户：

首次加载页面时获取3条数据
滚动加载另外3条数据(共6条)
导航到其他页面
返回列表页面时

数据会重置为最初的3条，而不是保持用户离开时的6条状态。这是因为Next.js的服务器组件在每次页面访问时都会重新执行，创建新的QueryClient实例并重新预取数据。

解决方案

1. 利用Next.js的缓存机制

Next.js提供了页面级缓存配置选项，可以通过设置适当的staleTime来控制数据的缓存行为。这种方法最简单，但灵活性较低。

2. 服务器端预取多页数据

更优雅的解决方案是在服务器端预取多页数据：

queryClient.prefetchInfiniteQuery({
  queryKey: ["active-moments"],
  queryFn: () => getActiveMoments({ limit: 3 }),
  initialPageParam: "",
  pages: 2 // 预取2页数据
})

这样初始加载就能获取更多数据，减少用户需要手动加载的次数。

3. 结合URL参数保持状态

最佳实践是将当前页码或游标保持在URL中：

// 使用类似?page=2的URL参数
const searchParams = useSearchParams()
const page = searchParams.get('page') || '1'

然后在服务器组件中根据URL参数决定预取哪些数据。这种方法不仅解决了状态保持问题，还支持直接链接到特定页面的场景。

实现细节

服务器组件优化

在服务器组件中，我们应该根据URL参数决定预取策略：

export default async function Actives({ searchParams }) {
  const queryClient = getQueryClient()
  const page = searchParams.page || 1
  
  await queryClient.prefetchInfiniteQuery({
    queryKey: ["active-moments", page],
    queryFn: () => getActiveMoments({ limit: 3, page }),
    initialPageParam: "",
    pages: page > 1 ? page : 2 // 第一页预取2页数据
  })
  
  // ...其余代码
}

客户端组件增强

客户端组件需要同步URL状态：

export function ActiveMoments() {
  const [searchParams, setSearchParams] = useSearchParams()
  const page = parseInt(searchParams.get('page') || '1')
  
  const { data, fetchNextPage } = useSuspenseInfiniteQuery({
    // ...查询配置
  })
  
  const handleLoadMore = () => {
    fetchNextPage().then(() => {
      setSearchParams({ page: page + 1 })
    })
  }
  
  // ...渲染逻辑
}