故障排除

Tip

页面路由器

由于 Next.js 页面路由器 在 SSR 上下文中不可用，因此此钩子在 SSR/SSG 上将始终返回 null（或提供的默认值）。

此限制不适用于应用路由器。

注意事项

在同一键上使用不同的解析器

钩子基于每个键进行同步，因此如果您在同一键上使用不同的解析器，最后一个状态更新将传播到使用该键的所有其他钩子。这可能导致意外的状态，例如：

const [int] = useQueryState('foo', parseAsInteger)
const [float, setFloat] = useQueryState('foo', parseAsFloat)

setFloat(1.234)

// `int` 现在是 1.234，而不是 1

我们建议您将键/解析器对抽象成一个专用钩子来避免这种情况，并从值中派生所需的任何状态：

function useIntFloat() {
  const [float, setFloat] = useQueryState('foo', parseAsFloat)
  const int = Math.floor(float)
  return [{int, float}, setFloat] as const
}

客户端组件需要包装在 `<Suspense>` 边界中

您可能遇到过 Next.js 的以下错误消息：

Missing Suspense boundary with useSearchParams

使用像 useQueryState 这样的钩子的组件在页面组件中渲染时，应包装在 <Suspense> 中。将 ‘use client’ 指令添加到 page.tsx 文件是立即修复以使事情正常工作的方法，如果您正在定义使用客户端功能（像 nuqs 或 React Hooks）的组件：

'use client'

export default function Page() {
  return (
    <Suspense>
      <Client />
    </Suspense>
  )
}

function Client() {
  const [foo, setFoo] = useQueryState('foo')
  // ...
}

然而，下面的步骤表明了获得更好 UX 的最佳方法：分离服务器和客户端文件（并将客户端代码尽可能移到树的最低层，以预渲染外部壳）。

推荐的方法是：

保持 page.tsx 作为服务器组件（无 'use client' 指令）
将客户端功能移动到一个单独的客户端文件。
将客户端组件包装在 <Suspense> 边界中。

页面路由器

注意事项

在同一键上使用不同的解析器

客户端组件需要包装在 <Suspense> 边界中

On this page

客户端组件需要包装在 `<Suspense>` 边界中