nuqs 是面向 React 的类型安全 URL 查询状态管理库，定位类似 useState，但把状态保存在 URL 查询参数中，便于分享、刷新保持与浏览器前进后退。
用途：用于在 React 中实现 URL 查询状态、同步 state 与 URL、构建可筛选/排序列表、带 URL 状态的分页、搜索参数管理，以及服务端读取查询参数等场景。
主要能力：
- 适配器：需先用 NuqsAdapter 包裹应用，按框架选择 nuqs/adapters/next/app、next/pages、react、remix、react-router。
- 钩子：useQueryState 处理单参数，useQueryStates 处理多参数并支持部分更新与批量 await 更新。
- 内置解析器：parseAsString、parseAsInteger、parseAsFloat、parseAsHex、parseAsBoolean、parseAsIsoDateTime、parseAsTimestamp、parseAsArrayOf（可自定义分隔符）、parseAsJson、parseAsStringEnum、parseAsStringLiteral、parseAsNumberLiteral。
- 默认值与选项：withDefault 提供默认值；withOptions 可配置 history（push/replace）、shallow、scroll、throttleMs、clearOnDefault、startTransition。选项优先级为调用级 > 解析器级 > 钩子级 > 全局适配器。
- 更新方式：支持函数式更新、同一 tick 内批量更新、await 更新后返回 URLSearchParams。
- 加载状态：结合 React useTransition 与 startTransition 选项，可在服务端更新时显示加载状态。
- 自定义解析器：可用普通对象或 createParser 定义 parse/serialize，引用类型需提供 eq 以保证 clearOnDefault 正常。
- 服务端组件：Next.js 使用 createSearchParamsCache 定义缓存，调用 parse(searchParams) 获取类型安全值，嵌套组件可用 get。
- 复用模式：可集中定义共享解析器、用 urlKeys 映射短 URL 键、封装自定义 Hook。
- 测试：withNuqsTestingAdapter 支持传入 searchParams 与 onUrlUpdate，便于断言 URL 更新。
使用方式：先按框架包裹 NuqsAdapter，再用 useQueryState/useQueryStates 读写参数；服务端读取需调用 createSearchParamsCache 的 parse；测试用 withNuqsTestingAdapter。官方资料列出了需避免的问题：缺少适配器、适配器与路由不匹配、Next.js App Router 缺少 Suspense、同一键使用不同解析器、服务端忘记调用 parse、在服务端组件中使用客户端钩子、无默认值导致空值处理繁琐、有损序列化、引用类型缺少 eq。
适用场景：筛选排序列表、分页、搜索、需要 URL 可分享与可回退的状态管理，以及 Next.js 服务端与客户端共享查询参数。
限制：必须先配置适配器；客户端钩子仅用于客户端组件；具体版本兼容性、安装命令与许可证信息暂未提供。