关于 nuqs
nuqs 是一套面向 Next.js 应用的参考技能，提供类型安全的 URL 查询状态管理指南。规则按八个类别和影响优先级组织，供开发者实现、审查和排查 nuqs 用法时参考。
主要功能
- 01涵盖八类的 42 条优先级规则
- 02类型化解析器与适配器指南
- 03服务端组件集成实践
- 04URL 更新性能建议
- 05调试与测试指南
适用场景
- 01在 Next.js 应用中实现 URL 状态
- 02配置查询参数解析器
- 03审查服务端 nuqs 集成
- 04排查 URL 状态行为问题
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/nuqs确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
AGENTS.mdmetadata.jsonREADME.mdassets/templates/_template.mdreferences/_sections.mdadvanced-custom-parsers.mdadvanced-eq-function.mdadvanced-framework-adapters.mdadvanced-url-keys.mddebug-common-errors.mddebug-enable-logging.mddebug-testing.mdhistory-back-sync.mdhistory-push-navigation.mdhistory-replace-ephemeral.mdhistory-scroll-behavior.mdparser-array-format.mdparser-date-format.mdparser-enum-validation.mdparser-hex-colors.mdparser-index-offset.mdparser-json-validation.mdparser-use-typed-parsers.mdparser-with-default.mdperf-avoid-rerender.mdperf-clear-on-default.mdperf-debounce-search.mdperf-serialize-utility.mdperf-throttle-updates.mdserver-next15-async.md详细介绍
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 的状态使用 withDefaultparser-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- 对相关参数使用 useQueryStatesstate-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 中使用 createSearchParamsCacheserver-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- 限制 URL 快速更新的频率perf-clear-on-default- 使用 clearOnDefault 保持 URL 简洁perf-avoid-rerender- 对使用 URL 状态的组件进行记忆化perf-serialize-utility- 使用 createSerializer 生成链接 URLperf-debounce-search- 更新 URL 前对搜索输入进行防抖处理
6. 历史记录与导航（中）
history-push-navigation- 对类似导航的状态使用 history:pushhistory-replace-ephemeral- 对临时状态使用 history:replacehistory-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 缩短 URLadvanced-eq-function- 为对象解析器实现 eq 函数advanced-framework-adapters- 使用特定框架的适配器
使用方法
阅读各个参考文件，了解详细说明和代码示例：
参考文件
| 文件 | 描述 |
|---|---|
| AGENTS.md | 包含所有规则的完整汇编指南 |
| references/_sections.md | 分类定义和排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本和参考信息 |
评论
支持 Markdown