nuqs

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. 服务端集成（HIGH）

• server-search-params-cache — 在服务端组件中使用 createSearchParamsCache（或 createLoader）
• server-shallow-false — 使用 shallow:false 触发服务端重新渲染
• server-use-transition — 集成 useTransition 以实现加载状态
• server-parse-before-get — 在服务端组件中先调用 parse()，再调用 get()
• server-next15-async — 处理 Next.js 15+ 中的异步 searchParams

5. 性能优化（MEDIUM）

• 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. 历史记录与导航（MEDIUM）

• history-push-navigation — 选择 history:push 还是 history:replace
• history-scroll-behavior — 控制 URL 变化时的滚动行为

7. 调试与测试（LOW-MEDIUM）

• debug-enable-logging — 启用调试日志以排查问题
• debug-testing — 测试带有 URL 状态的组件

8. 高级模式（LOW）

• advanced-custom-parsers — 为复杂类型创建自定义解析器
• advanced-url-keys — 使用 urlKeys 缩短 URL
• advanced-eq-function — 为对象解析器实现 eq 函数
• advanced-framework-adapters — 使用特定框架的适配器
• advanced-process-url-search-params — 使用 processUrlSearchParams 规范化 URL 结构（v2.6+）

使用方法

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

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

参考文件

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