如何在现有React树中正确使用hydrate/hydrateRoot？代码正确性咨询

一、核心使用原则 #

• 服务端渲染（SSR）生成的HTML必须与客户端React组件渲染的输出完全匹配（包括DOM结构、属性、文本内容），这是hydrate正常工作的前提，任何不匹配都会引发DOM操作异常。
• 禁止手动修改hydrate目标容器的innerHTML（除非是初始化SSR内容），所有DOM变更必须由React接管。
• React 18及以上版本优先使用hydrateRoot替代旧版hydrate，它支持并发渲染特性，API更稳定。

二、你提供的代码的核心问题 #

1. 手动操作innerHTML破坏React DOM管理：在hydrate前执行domNode.innerHTML = html，相当于直接删除了React管理的DOM节点，React无法追踪这种外部修改，从而触发警告。
2. unmount时机错误：在调用unmountComponentAtNode时，容器内的DOM已经被手动修改，导致React找不到对应的组件实例，引发DOM操作错误。
3. 多React实例冲突：如果Web Worker中的SSR代码使用的React版本与客户端不一致，或打包时生成多份React副本，会导致unmountComponentAtNode无法识别目标容器内的组件实例（属于另一个React副本）。

三、异常解决方案及修正代码 #

针对异常1、2：避免手动修改DOM，让React全权管理 #

不要通过innerHTML直接覆盖容器内容，正确流程是：容器初始innerHTML为SSR生成的MyComponent对应HTML，后续内容更新通过React组件的props/状态驱动，而非手动操作DOM。

针对异常3：确保全局只有一份React实例 #

• 检查打包配置（Webpack/Vite等），将React、ReactDOM设置为外部依赖（external），避免打包时生成多份副本。
• Web Worker中的SSR代码必须使用与客户端相同的React依赖，禁止单独打包React。

修正后的React 18+兼容代码 #

import React, { useEffect, useRef } from 'react'
import { hydrateRoot } from 'react-dom/client'

export default function SSRHydrateWrapper({ html }: { html: string }) {
  const containerRef = useRef<HTMLDivElement>(null)
  const rootRef = useRef<ReactDOM.Root | null>(null)

  useEffect(() => {
    const container = containerRef.current
    if (!container) return

    // 仅初始化时注入SSR生成的HTML
    if (!container.innerHTML) {
      container.innerHTML = html
    }

    // 卸载旧的根实例
    if (rootRef.current) {
      rootRef.current.unmount()
      rootRef.current = null
    }

    // 创建新的hydrate根实例
    rootRef.current = hydrateRoot(container, <MyComponent />)

    // 组件卸载时清理根实例
    return () => {
      rootRef.current?.unmount()
      rootRef.current = null
    }
  }, [html])

  return <div ref={containerRef} />
}

关键修改说明 #

• 用hydrateRoot替代旧版hydrate，通过root.unmount()完成卸载，避免旧API的兼容性问题。
• 仅在容器为空时注入SSR HTML，避免覆盖React已管理的DOM。
• 用rootRef保存hydrate根实例，确保卸载操作针对同一个React实例，避免跨副本冲突。

四、Web Worker SSR场景额外注意事项 #

• Web Worker生成的SSR HTML必须与客户端MyComponent的渲染输出完全一致，哪怕是空格、属性顺序的差异都可能触发hydrate警告。
• SSR代码需避免使用客户端特有的API（如window、document），确保Worker环境兼容。
• 动态更新内容时，通过修改组件props或状态实现，禁止手动操作DOM。

内容的提问来源于stack exchange，提问作者Colin D