Next.js 中使用 next-usequerystate 处理动态默认值的实践

在 Next.js 应用开发中，我们经常需要处理 URL 查询参数。next-usequerystate 是一个优秀的库，它简化了查询参数的管理。然而，在使用过程中，开发者可能会遇到一个常见问题：默认值在构建时被硬编码，导致后续运行时无法动态更新。

问题背景

当我们在 Next.js 的服务端组件中使用 next-usequerystate 定义查询参数时，如果默认值是基于当前时间的动态值（如本月开始和结束日期），这些值会在构建时被固化。这意味着即使时间推移到下个月，默认值仍保持构建时的月份数据。

技术分析

这种行为的根本原因在于 Next.js 的静态优化机制。在构建时，所有导出的常量都会被计算并固化。对于日期相关的默认值，这显然不符合预期行为。

典型的错误用法如下：

export const searchParams = {
  dateRange: parseAsArrayOf(parseAsTimestamp).withDefault([
    dayjs().startOf("month").toDate(),
    dayjs().endOf("month").toDate()
  ])
};

解决方案

方法一：使用函数动态生成参数配置

将静态的参数配置改为函数形式，确保每次调用都能获取最新的默认值：

export const getSearchParams = () => ({
  dateRange: parseAsArrayOf(parseAsTimestamp).withDefault([
    dayjs().startOf("month").toDate(),
    dayjs().endOf("month").toDate()
  ])
});

方法二：在页面组件中动态设置默认值

另一种方法是在页面组件中动态计算默认值，然后传递给参数解析器：

export default async function Page({ searchParams }) {
  const defaultDateRange = [
    dayjs().startOf("month").toDate(),
    dayjs().endOf("month").toDate()
  ];
  
  const { dateRange } = await loadSearchParams(searchParams, {
    dateRange: parseAsArrayOf(parseAsTimestamp).withDefault(defaultDateRange)
  });
}

最佳实践建议

1. 区分静态和动态默认值：对于不会随时间变化的默认值，可以使用静态定义；对于动态值，应采用函数形式。

2. 性能考虑：虽然函数形式解决了动态性问题，但要注意避免不必要的重复计算。对于不频繁变化的动态值，可以考虑添加简单的缓存机制。

3. 一致性维护：确保客户端和服务端使用相同的默认值逻辑，避免出现渲染不一致的情况。

总结

在 Next.js 应用中处理动态默认值时，开发者需要特别注意构建时和运行时的差异。通过将参数配置改为函数形式，我们可以确保默认值能够根据实际运行时的状态动态计算，从而解决构建时固化的问题。这种方法既保持了代码的清晰性，又满足了业务需求。

对于需要同时处理服务端和客户端状态的情况，建议统一通过函数形式管理默认值，并在文档中明确标注哪些参数是动态的，以便团队协作和维护。