Next-Themes 项目中 useIsHydrated 替代 isMounted 的技术实践

在 React 应用开发中，处理组件水合状态是一个常见但容易被忽视的问题。本文将以 next-themes 项目中的一个技术讨论为切入点，深入分析 useIsHydrated 钩子的实现原理及其相对于传统 isMounted 方案的优势。

水合状态管理的痛点

在服务端渲染(SSR)和静态生成(SSG)的应用中，组件从服务端渲染到客户端激活的过程被称为"水合"(hydration)。开发者经常需要判断当前组件是否已完成水合过程，以避免服务端和客户端渲染不一致的问题。

传统解决方案通常使用 isMounted 标志位，但这种方案存在两个主要缺陷：

1. 首次渲染时总会返回 false，即使是在客户端导航的情况下
2. 无法跨组件共享水合状态，导致重复判断

useIsHydrated 的实现原理

useIsHydrated 钩子巧妙地利用了 React 18 引入的 useSyncExternalStore API，实现了高效且可靠的水合状态检测：

import { useSyncExternalStore } from "react"

function subscribe() {
    return () => { }
}

export function useIsHydrated(): boolean {
    return useSyncExternalStore(
        subscribe,
        () => true,
        () => false
    )
}

这个实现的核心在于：

• 服务端渲染时使用第三个参数返回 false
• 客户端渲染时使用第二个参数返回 true
• 空订阅函数确保不会产生不必要的重渲染

技术优势分析

相比传统 isMounted 方案，useIsHydrated 具有以下显著优势：

1. 即时响应：在客户端导航时立即返回 true，避免了不必要的等待
2. 状态共享：全局维护水合状态，新挂载的组件能立即获取正确状态
3. 性能优化：通过 useSyncExternalStore 实现，避免了不必要的状态更新
4. 类型安全：明确的布尔返回类型，便于类型推断和静态检查

实际应用场景

这个钩子在主题切换等场景特别有用，例如：

function ThemeToggle() {
  const isHydrated = useIsHydrated()
  const { theme, setTheme } = useTheme()

  if (!isHydrated) {
    return <div className="w-6 h-6" /> // 渲染占位符
  }

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? '☀️' : '🌙'}
    </button>
  )
}

兼容性考虑

虽然这个方案基于 React 18 的 API，但可以通过适当的 polyfill 向下兼容。对于不支持 useSyncExternalStore 的环境，可以回退到传统的 useState + useEffect 实现，虽然会牺牲部分性能优势。

总结

useIsHydrated 提供了一种更优雅、更高效的方式来处理水合状态问题，特别适合在 next-themes 这类需要处理服务端/客户端状态一致性的库中使用。这种模式也可以推广到其他需要感知渲染环境的场景，如表单处理、动画触发等，为开发者提供了更可靠的渲染状态管理工具。