47ng/next-usequerystate 在 Next.js 15 中的使用注意事项

在 Next.js 15 中，服务器组件的 searchParams 属性变成了一个 Promise 对象，这一变化影响了 47ng/next-usequerystate 库的使用方式。本文将详细介绍这一变化及其解决方案。

问题背景

在 Next.js 14 及更早版本中，页面组件的 searchParams 属性可以直接访问，开发者可以像使用普通对象一样使用它。然而，在 Next.js 15 中，为了优化性能，searchParams 属性变成了一个异步的 Promise 对象。

具体表现

当开发者尝试使用 next-usequerystate 库的 createSearchParamsCache 方法解析 searchParams 时，如果 searchParams 是 Promise 对象而未正确处理，会导致 withDefault 方法失效，返回 undefined 而不是预期的默认值。

解决方案

要解决这个问题，开发者需要在解析 searchParams 时使用 await 关键字。这可以确保在解析之前等待 Promise 解析完成。以下是两种等效的解决方案：

方案一：在 parse 方法前 await

const { q: query, sport: sports } = await createSearchParamsCache({
  q: parseAsString,
  sport: parseAsArrayOf<keyof typeof SPORTS>(
    parseAsStringEnum(Object.keys(SPORTS) as (keyof typeof SPORTS)[]),
  ).withDefault([]),
}).parse(searchParams);

方案二：在 searchParams 前 await

const resolvedSearchParams = await searchParams;
const { q: query, sport: sports } = createSearchParamsCache({
  q: parseAsString,
  sport: parseAsArrayOf<keyof typeof SPORTS>(
    parseAsStringEnum(Object.keys(SPORTS) as (keyof typeof SPORTS)[]),
  ).withDefault([]),
}).parse(resolvedSearchParams);

技术原理

Next.js 15 将 searchParams 改为 Promise 主要是为了支持更高效的服务器端渲染。通过异步获取查询参数，可以在数据准备好之前就开始渲染页面，提高首屏渲染速度。

next-usequerystate 库的 createSearchParamsCache 方法期望接收一个普通的对象，而不是 Promise 对象。因此，在使用前必须确保 Promise 已经解析完成。

最佳实践

1. 始终在异步组件中使用 await 处理 searchParams
2. 考虑在组件顶部统一解析所有查询参数
3. 对于复杂的参数处理逻辑，可以封装成单独的函数
4. 在类型定义中明确标记异步属性

兼容性考虑

如果项目需要同时支持 Next.js 14 和 15，可以使用条件判断：

const resolvedSearchParams = searchParams instanceof Promise 
  ? await searchParams 
  : searchParams;

这种写法可以确保代码在不同版本的 Next.js 中都能正常工作。

总结

Next.js 15 的这一变化虽然带来了小小的适配成本，但为性能优化提供了更多可能性。开发者在使用 next-usequerystate 库时，只需记住在解析前正确处理 Promise 即可保持原有功能。这一调整也符合现代前端开发中异步处理数据的最佳实践。