Next-useQueryState 中 setter 函数稳定性问题分析与解决方案

问题背景

在 Next.js 应用开发中，next-useQueryState 是一个常用的状态管理库，用于将组件状态同步到 URL 查询参数中。在版本升级到 v2 后，开发者发现了一个关键行为变化：update 函数（即状态设置器）的引用稳定性发生了变化。

现象描述

在 v1 版本中，useQueryState 返回的 setter 函数（类似于 React 的 useState 的 setter）具有稳定的引用，这意味着开发者可以安全地将其放入依赖数组而不会导致无限循环。然而在 v2 版本中，这个 setter 函数的引用变得不稳定，导致以下代码会产生无限循环：

const [,setUsername] = useQueryState("username")

useEffect(() => {
  console.log("Running setUsername")
  setUsername(null)
}, [setUsername]);

技术分析

v1 与 v2 实现差异

在 v1 版本中，setter 函数的依赖数组仅包含基本值：

[key, history, shallow, scroll, throttleMs, startTransition]

而在 v2 版本中，依赖项新增了 adapter 对象：

[key, history, shallow, scroll, throttleMs, startTransition, adapter]

问题根源

adapter 是一个复合对象，虽然其内部的 updateUrl 方法通过 useCallback 保持了稳定性，但 adapter 对象本身在每次渲染时都会被重新创建。这是因为：

return {
  searchParams: optimisticSearchParams,
  updateUrl,
  rateLimitFactor: 2
}

这种对象字面量的创建方式导致每次渲染都会生成新的对象引用，进而触发 setter 函数的重新创建。

解决方案演进

临时解决方案

开发者可以手动从依赖数组中移除 setter 函数，这在大多数情况下是可行的，因为 setter 函数的功能通常不会改变。但这违背了 React 的最佳实践，也使得 ESLint 的 react-hooks/exhaustive-deps 规则产生警告。

官方修复方案

项目维护者在 2.3.1 版本中修复了这个问题，主要改进包括：

1. 优化了 adapter 对象的创建方式，确保其引用稳定性
2. 减少了不必要的重新渲染
3. 保持了与 React useState 一致的行为约定

最佳实践建议

1. 依赖数组处理：即使 setter 函数现在是稳定的，也应考虑是否真的需要将其放入依赖数组。通常 setter 函数的功能不会改变，可以安全地省略。

2. 版本选择：建议升级到 2.3.1 或更高版本以获得最稳定的行为。

3. 性能监控：在复杂应用中，应注意观察 URL 状态更新对性能的影响，特别是当有多个查询参数同时更新时。

技术启示

这个问题展示了 React 中引用稳定性的重要性。在构建自定义钩子或状态管理库时：

• 应特别注意返回的函数和对象的引用稳定性
• 复合对象的创建应使用 useMemo 或其他缓存机制
• 保持与 React 原生钩子行为的一致性有助于降低开发者认知负担

通过这个案例，我们可以看到即使是经验丰富的开发者构建的成熟库，在版本升级时也可能引入微妙的破坏性变化，这强调了全面测试和谨慎升级的重要性。