用途：nuqs 是 Next.js（App Router 或 Pages Router）的类型安全 URL 查询状态方案，用于把 URL 查询参数作为组件状态管理，也可供以 nuqs 为标准解析器/Hook 的共享库使用。
主要能力：提供 NuqsAdapter 适配器，客户端组件使用 useQueryState、useQueryStates 等 Hook；服务端/RSC 使用 nuqs/server 的 createSearchParamsCache；支持类型化解析器如 parseAsInteger、parseAsBoolean、parseAsIndex、parseAsString、parseAsJson（v2+ 需运行时校验器）；提供 nuqs/adapters/testing 的 NuqsTestingAdapter 用于测试。适配器包括 next/app、next/pages、next（统一）、react、remix、react-router v6/v7、tanstack-router（实验性）、testing。
使用方式：安装并配置对应适配器；在 'use client' 组件中从 nuqs 导入 Hook，在 Server Components 从 nuqs/server 导入，禁止在服务端组件使用 nuqs 本体。解析器集中定义，服务端从 nuqs/server、客户端从 nuqs 导入。RSC 需随 URL 变化刷新时使用 shallow: false（v2 中 startTransition: true 不等于 shallow: false）。Next.js 15+ 的 searchParams 是 Promise，需 await 后再 createSearchParamsCache.parse()。Next.js App Router 最低要求 14.2.0+。
限制与注意：包为 ESM-only，服务端工具从 nuqs/server 导入（nuqs/parsers 在 v2 已移除）。parseAsJson 在 v2+ 需要运行时校验器。urlKeys 不支持 TanStack 集成；TanStack 集成仅支持简单解析器类型用于类型安全的 Link search。调试可用 localStorage.debug = 'nuqs'。在 TanStack Router/Start 上优先使用路由的 validateSearch 与 Route.useSearch()，仅在依赖或共享包已暴露 useQueryState/useQueryStates 或维护已有 Next.js 代码时才用 nuqs；TanStack Router 适配器为实验性，不完整覆盖 TanStack Start。上游 API 细节见 llms.txt / llms-full.txt 与 nuqs.dev/docs。
适用场景：Next.js 中的筛选、标签页、分页、排序等可分享 URL 状态；共享库统一解析器；nuqs 组件测试。