PAYATHON 2026

React 19 内联 ref cleanup 在并发回滚时为何报 TypeError?

数据阿明

结论

React 19 支持从内联 callback ref 返回 cleanup function,见 React 19 官方说明。仅凭这段代码和错误堆栈,无法确认是否存在“deferred transition 回滚导致 ref cleanup 失效”的 React 缺陷,也无法确定实际抛错的空引用来自哪里。

代码中可以确定的是,内联 callback ref 每次 render 都会创建新函数。更新提交时,如果 ref 函数发生变化,React 会先执行旧 ref 的 cleanup,再调用新 ref。即使 DOM 节点没有更换,图表也可能被销毁并重新初始化。callback ref 文档

可以先用 useCallback 减少图表重建,并通过异常断点定位实际出错的位置。useCallback 能减少生命周期调用,但不能证明根因已经修复。

useDeferredValue 为什么会影响触发条件

useDeferredValue 通常先用旧值更新界面,再尝试在后台使用新值 render。后台 render 可能被新的更新打断或放弃。useDeferredValue 文档

需要区分 render 和 commit:

  • render 计算要显示的内容,此时会创建 ref 函数,但创建函数并不会执行其中的 init。
  • commit 才会处理 ref 的挂载、替换和卸载。
  • setShowMetrics(false) 提交后,原先已经挂载的图表容器被移除,对应的 cleanup 会执行。

在这段代码中,图表在 ref 挂载时初始化。被放弃的后台 render 并不意味着图表先被创建,再通过 rollback 销毁。Render and Commit、callback ref 文档

useDeferredValue 会改变更新的次数和时序,内联 ref 则可能使已提交的更新触发额外的销毁和初始化。这可以解释移除 useDeferredValue 后现象为何发生变化,但还不能证明具体根因。useDeferredValue 也不会让 commit 中同步执行的 init 或 destroy 自动变成可中断任务。

为什么已有空值检查仍然报错

原代码中的 cleanup 是:

return () => {
  if (chartInstance) {
    chartInstance.destroy();
  }
};

chartInstance 是该次 ref 调用中的局部 const。如果它是 null,条件判断会跳过后面的访问。另一次 render 或 ref 解绑也不会让 React 自动把这个局部变量改成 null。

因此,不能直接把错误解释为“cleanup 执行时 chartInstance 已经被 React 清空”。还需要检查:

  • destroy() 内部是否访问了已经清空的对象。
  • 实际代码是否通过某个可变的 ref.current 获取实例,与简化示例存在差异。
  • 同一个实例是否还被其他 Effect、封装组件或事件处理函数销毁。
  • 堆栈和 source map 是否对应当前实际加载的构建。

safelyCallDestroy 这个名字也不能直接说明它调用的是图表的 destroy 方法。以 React v19.0.0 源码为例,ref cleanup 由 safelyDetachRef 处理,safelyCallDestroy 用于 Hook Effect 的清理调用。这份源码说明的是该版本中两条路径的区别,排查时仍应查看应用所用的版本。React v19.0.0 源码

先稳定 callback ref

下面的例子沿用题目中的 init 和 destroy 接口,补上了隐藏按钮,以便复现交互。所有 Hook 都放在条件返回之前:

import { useCallback, useDeferredValue, useState } from 'react';
import { ExternalChartEngine } from 'awesome-charts';

export default function Dashboard({ searchTerms }) {
  const [showMetrics, setShowMetrics] = useState(true);
  const deferredSearch = useDeferredValue(searchTerms);

  const chartRef = useCallback((element) => {
    if (!element) return;

    const chartInstance = ExternalChartEngine.init(element, {
      query: deferredSearch
    });

    return () => {
      if (chartInstance) {
        chartInstance.destroy();
      }
    };
  }, [deferredSearch]);

  if (!showMetrics) {
    return <div>Metrics Hidden</div>;
  }

  return (
    <div className="dashboard-container">
      <button type="button" onClick={() => setShowMetrics(false)}>
        Hide metrics
      </button>
      <div ref={chartRef} />
    </div>
  );
}

deferredSearch 不变时,useCallback 可以保持 ref 函数引用稳定,减少无关更新导致的图表重建。deferredSearch 改变时,ref 仍会更换,旧实例会被清理,随后用新的 query 初始化图表。

不要为了固定函数引用而将依赖数组改成 [],否则回调会继续使用首次 render 时捕获的 deferredSearch。如果希望保留图表实例、只更新查询,需要根据图表库实际提供的 API 设计更新逻辑。题目没有提供这部分接口,不能假设存在 update 或 setQuery 方法。

按这个顺序定位根因

  1. 在开发者工具中启用异常暂停,必要时同时暂停已捕获的异常。查看第一处抛错的表达式,确定究竟哪个对象为 null,不要只看最后打印出来的 React 堆栈。
  2. 给每次 init 创建的实例分配调试编号,记录初始化和 cleanup。检查同一实例是否被多个位置销毁,以及图表库是否共享了容器级或全局状态。
  3. 用一个仅记录调用、destroy 不访问外部状态的模拟实例替换图表引擎。保留 useDeferredValue、快速输入和隐藏操作。如果错误消失,继续检查真实图表库及其封装;如果仍然出现,再缩小 React 复现范围。
  4. 核对实际依赖版本和加载来源。使用 npm 的项目可以运行 npm ls react react-dom,检查版本是否匹配、是否存在多份依赖;随后确保 source map 对应同一构建。
  5. 如果模拟实例仍能稳定复现,整理包含准确 React、react-dom 版本、StrictMode 配置和操作步骤的最小示例,再判断是否属于 React 缺陷。现有信息不足以指定某个修复版本。

原示例没有展示调用 setShowMetrics 的入口,最小复现时需要补齐这个交互,否则无法完整重现描述中的触发过程。

清理逻辑的注意事项

StrictMode 在开发环境中会额外执行一次 callback ref 的 setup/cleanup,用来检查资源管理是否完整。每次 setup 都应取得自己负责的资源,cleanup 应释放对应资源,后续 setup 应能正常重新创建。StrictMode 相关说明

对于已返回 cleanup function 的 ref,React 解绑时会调用该函数,并跳过再次传入 null 的步骤。不要把同一实例的必要清理拆到这两条路径中。React 19 ref cleanup 说明

保留已经正常工作的 useRef + useEffect 方案也是合理选择。两种方案的调用条件和执行时机不同,切换后错误消失只能作为定位线索。若 Effect 负责条件显示的节点,需要确保节点重新出现时初始化会再次执行;将图表拆成随条件挂载和卸载的子组件,通常更容易管理这段生命周期。

备注:内容仅供参考。