Next.js 中使用 nuqs 处理默认查询参数的序列化问题

问题背景

在 Next.js 应用中使用 nuqs 库（版本 2.0.4）时，开发者遇到了一个关于查询参数序列化的特殊问题。当查询参数使用默认值时，序列化器会返回空字符串，这导致了一些意外的行为。

问题分析

nuqs 是一个用于管理 Next.js 应用路由中查询状态的库。在版本 2.0.0 中，库的一个重要默认行为发生了变化：clearOnDefault 选项从默认 false 改为了 true。这个变化虽然有助于保持 URL 的简洁性（不显示默认值的参数），但在某些场景下会带来不便。

具体表现为：

1. 当使用 createSerializer 创建序列化器时
2. 如果查询参数值等于其默认值
3. 序列化器会返回空字符串而非包含默认值的完整查询字符串

影响场景

这个问题特别影响以下使用场景：

• 开发者希望生成包含所有参数（包括默认值）的完整 URL
• 使用 Next.js 的 <Link> 组件时，空字符串会导致页面无法正确重新渲染
• 需要保持 URL 中参数可见性的情况

临时解决方案

在 nuqs 2.1.0 版本发布前，开发者可以通过为每个解析器单独设置 clearOnDefault: false 来解决这个问题：

const serialize = createSerializer({
  foo: parseAsString.withOptions({ clearOnDefault: false }),
  bar: parseAsInteger.withOptions({ clearOnDefault: false })
})

官方修复方案

nuqs 2.1.0 版本中对此问题进行了改进，现在 createSerializer 支持全局配置选项：

const serialize = createSerializer(
  {
    foo: parseAsString,
    bar: parseAsInteger
  },
  {
    clearOnDefault: false, // 全局控制是否清除默认值
    urlKeys: { /* 缩短查询参数键名的映射 */ }
  }
)

这个改进使得开发者可以：

1. 全局控制所有参数的 clearOnDefault 行为
2. 同时支持 URL 键名缩短功能
3. 保持与 useQueryStates 类似的行为一致性

最佳实践建议

1. 明确需求：根据你的应用场景决定是否需要显示默认值的参数
2. 版本兼容：升级到 nuqs 2.1.0+ 以获得更灵活的配置选项
3. 一致性：在整个应用中保持相同的 clearOnDefault 策略
4. 文档参考：详细阅读 nuqs 文档中关于序列化和参数处理的章节

总结

nuqs 库在处理 Next.js 查询参数方面提供了强大的功能，但默认行为的改变可能会影响现有应用。理解 clearOnDefault 选项的作用，并根据应用需求合理配置，可以避免类似问题。最新的 2.1.0 版本提供了更灵活的配置方式，建议开发者升级并使用新的全局配置选项来简化代码。