nuqs-v2

Next.js 和 React 的 nuqs 社区最佳实践

全面介绍如何使用 nuqs 在 Next.js、React Router、TanStack Router、Remix 和纯 React 中进行类型安全的 URL 查询状态管理。涵盖 nuqs v2.5–v2.9 的功能。包含 8 个类别中的 39 条规则，并按影响排序，为代码生成、重构和代码审查提供指导。

适用场景

在以下情况下参考这些指南：

• 使用 nuqs 实现基于 URL 的状态
• 在 Next.js 或 React Router 项目中设置 nuqs
• 配置 URL 参数解析器
• 将 URL 状态与服务器组件集成
• 优化 URL 更新性能（limitUrlUpdates、键隔离）
• 通过 Standard Schema 与 tRPC / TanStack Router / 表单共享解析器定义
• 调试 nuqs 相关问题

规则类别与优先级

优先级	类别	影响	前缀
1	解析器配置	CRITICAL	parser-
2	适配器与设置	CRITICAL	setup-
3	状态管理	HIGH	state-
4	服务器端集成	HIGH	server-
5	性能优化	MEDIUM	perf-
6	历史记录与导航	MEDIUM	history-
7	调试与测试	LOW-MEDIUM	debug-
8	高级模式	LOW	advanced-

快速参考

1. 解析器配置（CRITICAL）

• 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 在 URL 中显示从 1 开始的索引

2. 适配器与设置（CRITICAL）

• setup-nuqs-adapter — 使用 NuqsAdapter 包装应用
• setup-use-client — 为钩子添加 'use client' 指令
• setup-import-server — 从 nuqs/server 导入服务器端实用工具
• setup-nextjs-version — 确保 Next.js 版本兼容
• setup-shared-parsers — 在专用文件中定义共享解析器
• setup-default-options — 在 NuqsAdapter 上配置应用级默认选项（v2.5+）

3. 状态管理（HIGH）

• 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 — 在服务端组件中使用 createSearchParamsCache（或 createLoader）
• server-shallow-false — 使用 shallow:false 触发服务端重新渲染
• server-use-transition — 集成 useTransition 处理加载状态
• server-parse-before-get — 在服务端组件中调用 get() 前先调用 parse()
• 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 之外依赖键隔离（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+）

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

参考文件

文件	描述
compiled.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息

交互关系

• 与 ahooks-v3 互补，用于处理 URL 中未包含的分组状态或本地状态
• 与 tanstack-query-v5 互补，用于异步服务端数据（查询中的加载/错误状态）
• 状态决策树：可通过 URL 分享的 UI → nuqs；分组的临时 UI → ahooks；异步数据 → TanStack Query