React hydrateRoot 怎么把可恢复水合错误写入诊断日志

在创建水合根时，把 onRecoverableError 放进 hydrateRoot 的第三个参数。回调接收错误与组件上下文；把它们转换成受控的普通对象，再交给项目的日志出口。不要把回调放进 root.render，也不要为了补日志再创建一个根。

官方地址：https://react.dev/reference/react-dom/client/hydrateRoot

下面讨论一个可修改客户端启动入口的 SSR 应用。示例用于解释接入方式，没有实际运行或制造线上错误；它只写控制台，远程收集需要接入项目已有的日志服务。

页面已经显示了，为什么还需要这类日志？

恢复显示与初始内容一致是两件事。服务端 HTML 和客户端首次渲染应保持一致；React 能从部分错误中恢复，不代表原来的问题可以忽略。日志要回答的是“哪个构建、哪个页面类别、哪个组件附近出现过恢复”，而不是只留下“页面能用”。

先把诊断分成三部分：根入口注册回调，适配器整理错误字段，日志出口保存事件。这样以后把控制台替换为现有采集 SDK 时，不需要修改 App 的渲染逻辑。示例的 kind 使用较宽的 react-recoverable，不把每个回调事件都擅自标成某一种确定的文本不匹配。

一份能放进客户端入口的写法是什么？

假设 HTML 中已经有服务端为 App 生成的 root 内容，且项目有 JSX 编译配置。保留原来的 App 导入和服务端数据传递方式，把下面的适配器并入现有启动文件。示例中的构建标识需要由项目替换，不能原样当成真实发布版本。

import { hydrateRoot } from 'react-dom/client';
import App from './App.jsx';

// 这些是项目定义的页面类别和构建标识，不读取用户输入或完整 URL
const context = Object.freeze({
  pageKey: 'catalog',
  release: 'web-build-example',
  rootKey: 'main',
});

function shortText(value, limit) {
  return typeof value === 'string' ? value.slice(0, limit) : '';
}

function errorSummary(value) {
  // 只取需要的字符串字段，不直接序列化 Error 或递归遍历 cause
  if (value instanceof Error) {
    return {
      name: shortText(value.name, 80),
      message: shortText(value.message, 1200),
      stack: shortText(value.stack, 4000),
    };
  }
  return {
    name: 'NonErrorValue',
    message: shortText(typeof value, 80),
    stack: '',
  };
}

const recentKeys = new Set();
let recorded = 0;

function onRecoverableError(error, errorInfo) {
  try {
    // 每个页面实例最多记录十条；这是示例策略，不是 React 的限制
    if (recorded >= 10) return;

    const summary = errorSummary(error);
    const componentStack = shortText(errorInfo?.componentStack, 4000);
    const cause = error instanceof Error && error.cause !== undefined
      ? errorSummary(error.cause)
      : null;

    // 只抑制当前页面中完全相同的记录；不依赖报错文案识别错误类别
    const key = JSON.stringify([summary.name, summary.message, componentStack]);
    if (recentKeys.has(key)) return;

    const event = {
      kind: 'react-recoverable',
      occurredAt: new Date().toISOString(),
      ...context,
      error: summary,
      cause,
      componentStack,
    };

    // 此处是日志出口适配点；示例只写浏览器控制台，不发网络请求
    console.error('[react-diagnostic]', event);
    recentKeys.add(key);
    recorded += 1;
  } catch {
    // 诊断失败不再向外抛错，也不在失败分支递归上报
  }
}

const container = document.getElementById('root');
if (!container) {
  // 缺少宿主节点属于入口配置问题，不会由本回调自动兜底
  throw new Error('缺少 SSR 根节点');
}

// options 放在 hydrateRoot 的第三个参数；服务端必须生成相同的初始 App 内容
hydrateRoot(container, , { onRecoverableError });

这里故意没有读取页面正文、HTML、查询参数或表单内容。页面类别 pageKey 用固定业务标签，构建标识 release 用发布产物的版本。多根页面可以给每个入口独立的 rootKey，并为各根创建独立适配器状态，避免相互共享计数和去重集合。

示例无条件接入回调，方便说明位置。真实项目应把生产日志接入放进现有环境配置；开发环境可保留 React 默认错误处理，或结合已有开发覆盖层。不要随意修改默认诊断体验后，再把覆盖层没有出现误判为错误没有发生。

error.stack 和 componentStack 要保存哪一个？

两者用途不同，可以分字段保留。前者描述错误相关的 JavaScript 调用栈，后者提供 React 组件上下文，不能互相替代。error.cause 只在部分可恢复错误上存在，所以用可选字段表达，不要为了字段齐全构造一个假原因。

直接 JSON.stringify(error) 不能代替字段选择：它不等价于明确提取 message、stack 等内容。这里先构造普通对象，且只取一层 cause。若接入的 SDK 支持原始 Error，它的标准错误能力可以另行使用，但应避免在同一出口重复提交原始错误与自建事件。

日志代码自己出错，会不会影响恢复？

日志适配器应尽量保持独立。示例用 try/catch 包住读取、归一化和同步出口，失败时不继续抛错；失败分支也不再次调用自身。这是应用的隔离策略，不是回调让所有错误都自动消失。

当前示例没有 Promise。若将出口替换为异步上报，外层同步 try/catch 不会接住以后发生的拒绝，需要由 SDK 或返回 Promise 的明确拒绝处理承担。不要在回调里加入无界重试、等待网络成功后才继续的逻辑，或者通过 setState 再次触发页面更新来“确认上报”。

十条上限与完全相同内容的去重只针对本页面实例。刷新页面会重新计数；它们不等于服务端聚合，更不代表错误只发生了十次。分析记录时应注明可能被去重或限额，不能直接把日志条数当作真实错误发生次数。

哪些场景不应该靠这个回调处理？

框架已经调用 hydrateRoot，还能自己补一遍吗？应先使用框架提供的入口或错误报告扩展。不要对同一个宿主节点重复水合，也不要假设任何 SSR 框架都允许应用直接传根选项。

回调触发说明整棵树都重新渲染了吗？不能仅凭一次回调推导恢复范围、影响的 DOM 数量或用户可见后果。日志保存事实和上下文，范围判断要结合具体错误与应用结构。

它能记录所有浏览器错误吗？不能。该选项关注 React 自动恢复的错误；当前 React 文档另列了被错误边界捕获和未捕获的根错误回调，它们不是可恢复回调的别名。普通网络失败和入口配置异常也不会自动变成这里的事件。

能用 suppressHydrationWarning 让日志消失吗？不要把消除记录当作修复。先检查首屏数据、分支条件和初始 HTML 的一致性；对于确有必要的局部差异，应按官方约束单独设计，不用隐藏警告替代排查。

这份接入的有效结果是一条具有来源、构建与组件上下文的诊断事件。日志解决可观察性问题，首屏一致性仍由服务端与客户端渲染契约保证。

参考：React 官方 hydrateRoot 参数与生产错误日志说明。