用途
nuqs 是一个类型安全的 URL 查询状态管理库，支持 Next.js、React Router、TanStack Router、Remix 以及纯 React。本技能为社区整理的 nuqs 最佳实践指南，覆盖 nuqs v2.5–v2.9 版本，包含 8 个类别共 39 条规则，按影响程度排序，用于指导代码生成、重构与代码审查。
适用时机
在以下情况参考本指南：
- 使用 nuqs 实现基于 URL 的状态
- 在 Next.js 或 React Router 项目中设置 nuqs
- 为 URL 参数配置解析器
- 将 URL 状态与 Server Components 集成
- 优化 URL 更新性能（limitUrlUpdates、key isolation）
- 通过 Standard Schema 与 tRPC / TanStack Router / 表单共享解析器定义
- 调试 nuqs 相关问题
规则类别与优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 解析器配置 | 关键 | parser- |
| 2 | 适配器与设置 | 关键 | setup- |
| 3 | 状态管理 | 高 | state- |
| 4 | 服务端集成 | 高 | server- |
| 5 | 性能优化 | 中 | perf- |
| 6 | 历史与导航 | 中 | history- |
| 7 | 调试与测试 | 低-中 | debug- |
| 8 | 高级模式 | 低 | advanced- |
快速参考
1. 解析器配置（关键）
- parser-use-typed-parsers — 对非字符串值使用类型化解析器
- parser-with-default — 对非可空状态使用 withDefault
- parser-enum-validation — 对受限值使用枚举解析器
- parser-array-format — 选择正确的数组解析器格式
- parser-json-validation — 验证 JSON 解析器输入
- parser-date-format — 选择合适的日期解析器
- parser-index-offset — 使用 parseAsIndex 实现基于 1 的 URL 显示
2. 适配器与设置（关键）
- setup-nuqs-adapter — 用 NuqsAdapter 包裹应用
- setup-use-client — 为 hooks 添加 'use client' 指令
- setup-import-server — 从 nuqs/server 导入服务端工具
- setup-nextjs-version — 确保兼容的 Next.js 版本
- setup-shared-parsers — 在专用文件中定义共享解析器
- setup-default-options — 在 NuqsAdapter 上配置应用级默认值（v2.5+）
3. 状态管理（高）
- state-use-query-states — 对相关参数使用 useQueryStates
- state-clear-with-null — 用 null 清除 URL 参数
- state-avoid-derived — 避免从 URL 参数派生状态
- state-options-inheritance — 使用 withOptions 进行解析器级配置
- state-setter-return — 使用 setter 返回值访问 URL
- state-standard-schema — 使用 Standard Schema 进行跨库验证（v2.5+）
4. 服务端集成（高）
- server-search-params-cache — 对 Server Components 使用 createSearchParamsCache（或 createLoader）
- server-shallow-false — 使用 shallow:false 触发服务端重新渲染
- server-use-transition — 集成 useTransition 处理加载状态
- server-parse-before-get — 在 Server Components 中先调用 parse() 再调用 get()
- server-next15-async — 处理 Next.js 15+ 中的异步 searchParams
5. 性能优化（中）
- perf-throttle-updates — 使用 limitUrlUpdates 节流快速 URL 更新
- perf-debounce-search — 使用内置 limitUrlUpdates 对搜索输入进行防抖
- perf-clear-on-default — 使用 clearOnDefault 保持 URL 简洁
- perf-avoid-rerender — 对使用 URL 状态的组件进行记忆化（Next.js）
- perf-key-isolation — 在 Next.js 之外依赖 key isolation（v2.5+）
- perf-serialize-utility — 使用 createSerializer 生成链接 URL
6. 历史与导航（中）
- history-push-navigation — 选择 history:push 还是 history:replace
- history-scroll-behavior — 控制 URL 变化时的滚动行为
7. 调试与测试（低-中）
- debug-enable-logging — 启用调试日志进行故障排查
- debug-testing — 测试带 URL 状态的组件
8. 高级模式（低）
- advanced-custom-parsers — 为复杂类型创建自定义解析器
- advanced-url-keys — 使用 urlKeys 生成更短的 URL
- advanced-eq-function — 为对象解析器实现 eq 函数
- advanced-framework-adapters — 使用框架特定的适配器
- advanced-process-url-search-params — 使用 processUrlSearchParams 规范化 URL 形态（v2.6+）
如何使用
阅读各个参考文件以获取详细说明和代码示例：
- Section definitions — 类别结构与影响级别
- Rule template — 添加新规则的模板
参考文件
| 文件 | 描述 |
|---|---|
| compiled.md | 包含所有规则的完整编译指南 |
| references/_sections.md | 类别定义与排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本与参考信息 |
交互
- 与 ahooks-v3 互补，用于不在 URL 中的分组/本地状态
- 与 tanstack-query-v5 互补，用于异步服务端数据（来自查询的加载/错误）
- 状态决策树：URL 可分享的 UI → nuqs；分组临时 UI → ahooks；异步数据 → TanStack Query