Wagmi 在 Next.js 热重载时无限重连问题解析

问题现象

在使用 Next.js 开发基于 Wagmi 的 Web3 应用时，开发者会遇到一个棘手的问题：当进行热重载（Hot Reload）时，Wagmi 会陷入无限重连状态，表现为 isReconnecting: true 状态持续存在，无法自动恢复连接。

问题根源分析

经过深入调试，发现问题的核心在于 Wagmi 的 Hydrate 组件实现方式。具体表现为：

1. 状态管理异常：热重载时，Wagmi 的状态被意外清除，但重新水合（hydrate）的过程未能正确执行
2. Effect 依赖问题：useEffect 依赖项设置过于保守，导致热重载后必要的重新连接逻辑未能触发
3. 引用值不变：active ref 在热重载后保持 { current: false } 状态，阻止了 onMount 函数的执行

技术细节

Wagmi 原本的 Hydrate 实现采用了以下策略：

useEffect(() => {
  if (!active.current) return
  active.current = false
  if (!config._internal.ssr) return
  onMount()
}, [])

这种实现方式存在两个关键问题：

1. 依赖数组为空，React 无法感知需要重新执行 effect
2. active ref 在热重载后保持 false，导致后续连接逻辑被跳过

解决方案

经过社区贡献者的调试，提出了以下改进方案：

useEffect(() => {
  if (!config._internal.ssr) return
  onMount()
}, [onMount])

这个修改带来了以下改进：

1. 添加了 onMount 作为依赖项，确保热重载后能重新执行
2. 移除了 active ref 的检查，允许必要的重新连接
3. 保持了 SSR 场景下的正确行为

影响范围

该问题主要影响以下场景：

1. Next.js 应用中使用 App Router
2. 开发环境下的热重载操作
3. 使用服务器端重新验证（revalidate）功能的场景

最佳实践建议

对于正在使用 Wagmi 的开发者，建议：

1. 确保使用最新版本的 Wagmi，该问题已在后续版本修复
2. 对于自定义连接逻辑，考虑添加重连超时机制
3. 在开发过程中，可以通过强制刷新页面来临时解决连接卡住的问题

总结

Wagmi 的热重载重连问题揭示了前端状态管理在开发环境下的特殊挑战。通过理解 React 的 effect 执行机制和状态保持原理，开发者可以更好地处理类似问题。这个案例也展示了开源社区如何协作解决复杂的技术问题，为 Web3 开发者提供了更稳定的开发体验。