NuQS 在 Next.js 页面路由中处理重复查询参数的 Bug 解析

在 Next.js 应用开发中，URL 查询参数的处理是一个常见需求。NuQS 作为一个专门用于管理查询字符串状态的库，近期被发现存在一个关于重复查询参数处理的 Bug。

问题背景

当 URL 中包含多个同名查询参数时，例如 ?test=1&test=2，NuQS 在处理这些参数时会出现异常。具体表现为：虽然 URL 中仍然保留着多个参数值，但通过 router.query 获取到的结果却只包含最后一个参数值，而不是预期的数组形式。

技术分析

这个问题的根源在于 NuQS 内部使用了 Object.fromEntries 方法来重构搜索参数。这个方法在处理具有相同键的多个条目时，会自动覆盖之前的值，只保留最后一个条目。这与 URL 查询参数的标准行为不符，因为 URL 规范允许存在多个同名参数。

解决方案

NuQS 开发团队迅速响应并修复了这个问题。修复方案主要针对 adapters/next/impl.pages.ts 文件中的相关代码。现在，当遇到多个同名查询参数时，系统会正确地将这些值收集到一个数组中，而不是简单地覆盖。

影响范围

这个 Bug 主要影响使用 Next.js 页面路由（pages router）的项目。如果你在应用中需要处理数组形式的查询参数，特别是在以下场景中：

1. 多选筛选功能
2. 复合查询条件
3. 需要保留历史参数的场景

建议尽快升级到修复版本。

升级建议

如果你正在使用 NuQS 并遇到类似问题，建议升级到 2.4.3 或更高版本。这个版本已经包含了完整的修复方案，能够正确处理重复查询参数的情况。

总结

查询参数处理是 Web 开发中的基础功能，但细节决定体验。NuQS 的这次修复体现了对标准规范的尊重和对开发者体验的关注。作为开发者，了解这些底层机制有助于我们在遇到类似问题时更快地定位和解决。