nuqs 是一个用于 Next.js 的类型安全 URL 查询参数状态管理工具。本技能是面向 Next.js 应用的社区 nuqs 最佳实践指南，涵盖使用 nuqs 进行类型安全 URL 查询状态管理的完整内容，包含 42 条规则，分为 8 个类别，并按影响程度排序，用于指导代码生成、重构和代码审查。
适用时机
在以下情况参考这些指南：
- 使用 nuqs 实现基于 URL 的状态
- 在 Next.js 项目中配置 nuqs
- 为 URL 参数配置解析器
- 将 URL 状态与服务端组件集成
- 优化 URL 更新性能
- 排查 nuqs 相关问题
规则类别（按优先级）
- 解析器配置（CRITICAL，前缀 parser-）
- 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 显示
- parser-hex-colors：对颜色值使用 parseAsHex
- 适配器与初始化（CRITICAL，前缀 setup-）
- setup-nuqs-adapter：用 NuqsAdapter 包裹应用
- setup-use-client：为 hooks 添加 'use client' 指令
- setup-import-server：从 nuqs/server 导入服务端工具
- setup-nextjs-version：确保 Next.js 版本兼容
- setup-shared-parsers：在专用文件中定义共享解析器
- 状态管理（HIGH，前缀 state-）
- 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
- 服务端集成（HIGH，前缀 server-）
- server-search-params-cache：为服务端组件使用 createSearchParamsCache
- server-shallow-false：使用 shallow:false 触发服务端重新渲染
- server-use-transition：集成 useTransition 处理加载状态
- server-parse-before-get：在服务端组件中先调用 parse() 再调用 get()
- server-share-parsers：在客户端与服务端之间共享解析器
- server-next15-async：处理 Next.js 15+ 中的异步 searchParams
- 性能优化（MEDIUM，前缀 perf-）
- perf-throttle-updates：使用 limitUrlUpdates 节流 URL 更新
- perf-clear-on-default：使用 clearOnDefault 保持 URL 简洁
- perf-avoid-rerender：对使用 URL 状态的组件进行记忆化
- perf-serialize-utility：使用 createSerializer 生成链接 URL
- perf-debounce-search：对绑定服务端的搜索更新进行防抖
- 历史与导航（MEDIUM，前缀 history-）
- history-push-navigation：对类似导航的状态使用 history:push
- history-replace-ephemeral：对临时状态使用 history:replace
- history-scroll-behavior：控制 URL 变化时的滚动行为
- history-back-sync：处理浏览器后退/前进导航
- 调试与测试（LOW-MEDIUM，前缀 debug-）
- debug-enable-logging：启用调试日志进行排查
- debug-common-errors：诊断常见 nuqs 错误
- debug-testing：测试带 URL 状态的组件
- 高级模式（LOW，前缀 advanced-）
- 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
针对上述每条与任务匹配的规则以及每个扫描命中项，阅读 references/<rule-id>.md，了解其重要性以及错误与正确代码的对比。