nuqs

Next.js 的社区 nuqs 最佳实践

全面指南：在 Next.js 应用中使用 nuqs 进行类型安全的 URL 查询状态管理。包含 8 个类别中的 42 条规则，按影响程度排序，用于指导代码生成、重构和代码审查。

适用场景

在以下场景中参考这些指南：

• 使用 nuqs 实现基于 URL 的状态
• 在 Next.js 项目中配置 nuqs
• 配置 URL 参数解析器
• 将 URL 状态与 Server Components 集成
• 优化 URL 更新性能
• 调试 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 - 对不可为 null 的状态使用 withDefault
• parser-enum-validation - 对受限值使用枚举解析器
• parser-array-format - 选择正确的数组解析器格式
• parser-json-validation - 验证 JSON 解析器的输入
• parser-date-format - 选择合适的日期解析器
• parser-index-offset - 使用 parseAsIndex 显示从 1 开始的 URL 索引
• parser-hex-colors - 对颜色值使用 parseAsHex

2. 适配器与设置（CRITICAL）

• setup-nuqs-adapter - 使用 NuqsAdapter 包装应用
• setup-use-client - 为 Hooks 添加 'use client' 指令
• setup-import-server - 从 nuqs/server 导入服务端实用工具
• setup-nextjs-version - 确保 Next.js 版本兼容
• setup-shared-parsers - 在专用文件中定义共享解析器

3. 状态管理（HIGH）

• state-use-query-states - 对相关参数使用 useQueryStates
• state-functional-updates - 对派生状态使用函数式更新
• state-clear-with-null - 使用 null 清除 URL 参数
• state-controlled-inputs - 正确处理受控输入值
• state-avoid-derived - 避免从 URL 参数派生状态
• state-options-inheritance - 使用 withOptions 配置解析器级选项
• state-setter-return - 使用 setter 返回值访问 URL

4. 服务端集成（HIGH）

• server-search-params-cache - 在 Server Components 中使用 createSearchParamsCache
• server-shallow-false - 使用 shallow:false 触发服务端重新渲染
• server-use-transition - 集成 useTransition 以显示加载状态
• server-parse-before-get - 在 Server Components 中先调用 parse()，再调用 get()
• server-share-parsers - 在客户端和服务端之间共享解析器
• server-next15-async - 处理 Next.js 15+ 中的异步 searchParams

5. 性能优化（中）

• perf-throttle-updates - 使用 limitUrlUpdates 对 URL 更新进行节流
• perf-clear-on-default - 使用 clearOnDefault 清理 URL
• perf-avoid-rerender - 对使用 URL 状态的组件进行记忆化
• perf-serialize-utility - 使用 createSerializer 生成链接 URL
• perf-debounce-search - 对发往服务端的搜索更新进行防抖

6. 历史记录与导航（中）

• history-push-navigation - 对类似导航的状态使用 history:push
• history-replace-ephemeral - 对临时状态使用 history:replace
• history-scroll-behavior - 控制 URL 更改时的滚动行为
• history-back-sync - 处理浏览器的后退/前进导航

7. 调试与测试（低—中）

• debug-enable-logging - 启用调试日志以排查问题
• debug-common-errors - 诊断常见的 nuqs 错误
• debug-testing - 测试使用 URL 状态的组件

8. 高级模式（低）

• advanced-custom-parsers - 为复杂类型创建自定义解析器
• advanced-url-keys - 使用 urlKeys 缩短 URL
• advanced-eq-function - 为对象解析器实现 eq 函数
• advanced-framework-adapters - 使用特定框架的适配器

使用方法

首先在项目根目录中运行：

npx -y @pymodel/react-frontend-skills detect             # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill nuqs  # deprecated APIs → rule IDs

对于上面与任务匹配的每条规则，以及每个 scan 命中项，请阅读 references/<rule-id>.md：了解其重要性，然后查看错误与正确的代码。