React AI useSyncExternalStore：快照一致性与扇出回归门禁

React Context 性能陷阱 已覆盖拆 Context、稳定 value、选择性订阅与状态库选型，本篇不再论证这些通用解法。这里聚焦 useSyncExternalStore 的缓存快照、原子通知、服务端首快照和竞态一致性，并为 AI 流状态规定每次 commit 的扇出上限；流式界面提交频率预算 另行控制一秒产生多少次 commit。

先冻结快照域与 fanout 基线

把状态按事实来源和频率分为四域：当前 run 的高频文本；消息列表的低频结构；连接、错误和停止按钮所需的运行元数据；额度、模型选择和侧栏等会话外状态。一个快照只包含该域消费者真正需要的值。高频文本不能通过顶层 messages.map(...) 传播，历史消息也不能因为当前片段到达而获得新对象引用。

基准树固定 120 条历史消息、8 个侧栏小组件、1 个编辑器和1个活动回答。重放 800 个片段，频率为每秒 25 个；期间编辑器输入 100 次，连接状态切换两次，额度更新一次。报告记录 React 19.2.4、浏览器构建、生产代码摘要，以及无 Strict Mode 的 profiling 构建。门禁要求：流期间每个历史消息行额外 render 不超过 1 次；额度与侧栏在其 slice 未变时为 0 次；活动回答 Profiler 子树的 actualDuration P95 小于 8 毫秒；一次片段批次触达的组件数 P95 不超过批准基线的 110%；编辑器输入值和最终回答摘要完全正确。

<Profiler> 的 actualDuration 只用于比较该子树的 render 时间，baseDuration 用于观察未记忆整棵子树的估算 render 成本；两者都不是完整 commit、DOM mutation、layout effect、style/layout 或 paint 时长。完整更新成本由 React Performance Tracks 或浏览器 trace 归因，再用 LoAF、Event Timing 与 commit-to-paint 近似补齐。正式生产构建不依赖 Profiler 回调做业务逻辑，线上只采集 User Timing、INP 与采样 render 计数。开发 Strict Mode 可能重复调用渲染，不能直接拿它的次数作为发布阈值。React 性能优化 中的 memo 化只有在 props 引用稳定后才有意义。

外部 store 必须返回缓存快照

高频运行可以拥有独立外部 store，组件用 useSyncExternalStore 订阅。getSnapshot 在数据未变化时必须返回同一个不可变对象，否则 React 会持续认为 store 已更新。不要让每个订阅者拿到完整会话后在 render 中临时筛选；为 runText(runId)、runMeta(runId) 等域建立独立 store 或带相等比较的稳定 selector 层。

type RunTextSnapshot = Readonly<{ revision: number; text: string }>;

function useRunText(runId: string) {
  const store = getRunTextStore(runId);
  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
}

服务端快照和首次客户端快照必须一致，否则会把性能改造变成 hydration 错误。片段批次提交时，store 先原子替换 snapshot，再通知订阅者；通知期间再次写入要排到下一批，不能让两个组件在同一次 React 工作中读到不同 revision。断开 run 时清理订阅和缓冲，但保留已提交消息事实。状态分层可衔接 React AI 会话状态契约，外部 store 只是视图投影，不是持久化来源。

低频域不必全部外移。模型选择、主题或权限可以保留独立 Context，Provider value 由实际字段稳定化，并放在尽可能深的位置。禁止把 store 实例、当前文本和所有 action 重新打包进一个顶层对象；这种“统一 API”会恢复原来的广播扇出。React 状态管理选型 可用于决定库，门禁不应依赖某个库名称。

竞态测试同时验证性能和一致性

自动化在同一帧注入多片段、订阅回调中取消 run、卸载再挂载活动回答、切换会话后让旧 run 晚到，并在渲染中故意读取 text 与 revision。断言 revision 单调、旧 run 不触达新页面、取消后订阅数归零、任何组件看到的 text 都对应同一 revision。性能脚本把每次 React 更新涉及的组件 ID、Profiler render 时长与对应浏览器 trace 区间写入报告，不能只看总耗时，因为高速机器会掩盖错误扇出。

上线前保留 Context 适配器和新 store 双读一周，影子比较两边的规范快照摘要，不让两边同时驱动 DOM。先只把活动文本切到新订阅，确认一致后再迁移 run 元数据。出现快照不一致、订阅持续增长、历史行 render 超线、活动回答 actualDuration P95 增长 20% 或 hydration 恢复错误时，开关切回旧投影；新 store 停止通知并排空监听器。这样回滚恢复的是明确的数据路径，而不是临时给更多组件加 memo。

延伸阅读

• React Context 性能陷阱
• React AI 会话状态契约
• React 性能优化
• React 状态管理选型