React Query 中 HydrationBoundary 导致 Vercel 构建超时的解决方案

在使用 React Query 进行服务端数据预取时，开发者可能会遇到一个特殊问题：在本地开发环境下运行正常的代码，部署到 Vercel 时却出现构建超时错误。这种情况通常与 HydrationBoundary 的使用方式有关。

问题现象

典型的代码结构如下：

// 服务端组件
const DashboardPage = async () => {
  const queryClient = new QueryClient()

  await queryClient.prefetchQuery({
    queryKey: ['profile'],
    queryFn: userService.getProfile
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Header />
    </HydrationBoundary>
  )
}

// 客户端组件
'use client'
export const Header = () => {
  const { data } = useQuery({
    queryKey: ['profile'],
    queryFn: userService.getProfile
  })

  return <div>{data?.name}</div>
}

在 Vercel 部署时，系统会报错"Static page generation timeout"，提示静态页面生成超时。

问题根源

这个问题主要有两个关键点：

1. Promise 解析问题：在服务端预取数据时，直接传递函数引用(userService.getProfile)可能导致 Promise 无法正确解析
2. 环境差异：Vercel 的构建环境与本地开发环境存在差异，对异步操作的处理更为严格

解决方案

修改服务端组件中的 prefetchQuery 调用方式：

await queryClient.prefetchQuery({
  queryKey: ['profile'],
  queryFn: () => userService.getProfile() // 使用箭头函数包装
})

这个修改确保了：

1. 明确创建了一个返回 Promise 的函数
2. 使 React Query 能够正确追踪异步操作的状态
3. 避免了潜在的 Promise 解析问题

最佳实践

在使用 React Query 进行服务端渲染时，建议：

1. 总是使用箭头函数包装查询函数
2. 在服务端组件中确保所有异步操作都有明确的等待
3. 考虑添加错误边界处理预取可能失败的情况
4. 对于关键数据，可以添加超时处理逻辑

通过这种方式，可以确保代码在不同环境下都能稳定运行，避免部署时的意外错误。