React useRef 的物理绑定机制：源码解析在 completeWork 阶段如何将物理 DOM 实例句柄写入 ref.current 指针

各位前端架构师、React 源码探索者，以及那些“不搞懂 React 内部原理就睡不着觉”的朋友们，大家好！

今天我们不开设常规的入门课，我们要来点硬核的。我们要进行一场源码级别的“外科手术”，把 React 的核心组件 useRef 拆开，看看它到底是如何在 completeWork 阶段，把那个虚无缥缈的“虚拟 DOM”变成实实在在的“物理 DOM”，并把这个物理地址塞进 ref.current 这个指针里的。

这就像是一场特工接头，useRef 是那个特工，completeWork 是那个特工接头地点，而 DOM 节点就是他们交换的“密钥”。

准备好了吗？让我们把代码编辑器打开，把咖啡续上，开始今天的源码解析之旅。

第一部分：为什么我们需要这场“物理绑定”？

想象一下，你在写代码。你写了一个 <div ref={myRef}>Hello World</div>。在 JavaScript 层面，myRef 不过是一个普通的对象 { current: null }。这时候，浏览器屏幕上还没有这个 div，它在虚拟的世界里。

React 的核心哲学是“声明式”，也就是“告诉我你想要什么，不要告诉我怎么去做”。所以我们写 JSX，React 读 JSX，然后 React 去构建 DOM。

但是，有时候我们需要“命令式”的操作。比如，我要获取这个 div 的坐标，或者我要调用原生的 API，这时候我就需要那个 current 指针真的指向那个 HTML 元素。这个过程，就是我们今天要讲的——物理绑定。

这个过程发生在哪里？发生在 completeWork 阶段。这是 React 协调算法中极其关键的一环，是“渲染”这一庞大工程的后半场。

第二部分：走进 completeWork 的世界

在进入源码之前，你得先理解 completeWork 是干什么的。

React 渲染分为三个主要阶段：

1. Render（渲染）： 生成 Fiber 树（工作单元树）。这是“构思”阶段。
2. Commit（提交）： 将变更应用到真实 DOM。这是“施工”阶段。
3. CompleteWork（完成工作）： 这是介于两者之间的桥梁。在这个阶段，React 递归地遍历 Fiber 树，根据节点的类型，决定是创建新的 DOM 节点，还是复用旧的，并处理各种副作用，包括最重要的——Ref。

你可以把 completeWork 想象成是一个装修队的工头。他手里拿着蓝图（Fiber 节点），开始往墙上刷漆（创建 DOM）。这时候，他必须得确保每一个插座（DOM）都被正确连接。

第三部分：源码解剖 – HostComponent 的诞生

让我们把目光聚焦在 ReactFiberCompleteWork.js 文件中。当 completeWork 遇到一个 HostComponent（比如 div, span, p），它会做些什么？

首先，它会查看当前的 current 节点（也就是上一次渲染留下的旧树）和 workInProgress 节点（也就是正在构建的新树）。React 的核心机制叫“复用”。如果两个节点类型一样、key 一样，React 会尝试把旧节点的物理实例（DOM）复用给新节点。

这就是魔法发生的地方。

1. 创建物理实例

如果这是一个全新的节点（比如第一次渲染），或者需要重新创建，React 会调用 createInstance 函数。在浏览器环境中，这通常就是 document.createElement('div')。

// 这是一个高度简化的伪代码，模拟 React 的逻辑
function completeWork(current, workInProgress) {
  const tag = workInProgress.tag;

  switch (tag) {
    case HostComponent: {
      // 处理 DOM 节点
      const type = workInProgress.type; // 'div'
      const props = workInProgress.pendingProps; // { ref: myRef, children: ... }

      // 1. 创建物理 DOM 实例
      const instance = createInstance(type, props, rootContainerInstance, hostContext, workInProgress);

      // 2. 将 DOM 挂载到 Fiber 节点上
      workInProgress.stateNode = instance;

      // 3. 处理子节点（递归）
      // 注意：completeWork 必须先处理完所有子节点，才能处理父节点的 Ref
      // 这就像盖房子，得先盖好地下的管道，才能接电源线

      // ... 递归处理子节点 (completeChildren) ...

      // 4. 物理绑定：处理 Ref
      // 只有当所有子节点都处理完了，父节点的 DOM 实例才真正存在
      // 这时候，我们就可以把 Ref 指向这个 DOM 实例了！
      commitWork(workInProgress); 

      return null;
    }
  }
}

注意上面的第3步注释。这是一个非常重要的细节。为什么 Ref 绑定要放在递归子节点之后？

因为 DOM 是层级结构。父节点的 Ref 必须指向父节点的真实 DOM，而这个真实 DOM 必须在所有子节点的 DOM 创建完毕、挂载完毕之后才真正具备“物理实体”。如果父节点想通过 Ref 访问子节点，子节点必须先存在。这体现了 React 递归逻辑的严谨性。

第四部分：Ref 的魔法赋值

现在，让我们深入到 commitWork（或者是更底层的 Ref 处理逻辑）中。这是整个机制的核心。

当一个 Fiber 节点处理完子节点，拥有了 instance（物理 DOM 实例）后，它会检查自己是否有 ref 属性。

// 模拟 React 源码中处理 HostComponent Ref 的逻辑
function commitWork(fiber) {
  // 检查 Fiber 上是否有 ref
  if (fiber.ref !== null) {
    const instance = fiber.stateNode; // 这就是我们的物理 DOM 实例

    // 关键代码来了！
    // 这里就是物理绑定的具体实现
    // React 会更新 ref.current 指针，指向这个 DOM 实例
    const currentRef = fiber.ref;

    if (typeof currentRef === 'function') {
      // 如果 ref 是一个函数
      currentRef(instance);
    } else {
      // 如果 ref 是一个对象（我们的 useImperativeHandle 或 useRef）
      currentRef.current = instance;
    }
  }
}

场景重现：useRef 的奥秘

让我们回顾一下 const myRef = useRef(null)。

1. Render 阶段： React 调用你的组件函数。useRef 返回一个对象 { current: null }。这个对象被 React 存储在某个地方（通常是 FiberNode.memoizedState）。此时，myRef.current 是 null。
2. CompleteWork 阶段：
   • React 递归处理 Fiber 树。
   • 它发现了一个 <div ref={myRef}>。
   • 它创建了 div 元素。
   • 它找到了 myRef 对象。
   • 它执行了 myRef.current = divElement。
3. Commit 阶段： React 将变更提交到 DOM。但此时，myRef.current 已经在 completeWork 阶段被更新了！

结论： 当你渲染完成后，myRef.current 已经指向了真实的 DOM 节点。这就是为什么在 useEffect 里你可以直接用 myRef.current.scrollIntoView() 而不用担心它是 null 的原因——因为 completeWork 已经把它“焊死”在那里了。

第五部分：深入递归 – 嵌套结构的物理绑定

DOM 是嵌套的，Ref 也是。completeWork 如何处理这种复杂的嵌套关系？我们来看一个例子：

function Parent() {
  const parentRef = useRef(null);
  return (
    <div ref={parentRef}>
      <div>
        <span ref={spanRef}>Hello</span>
      </div>
    </div>
  );
}

当 React 走进 completeWork 的递归逻辑时，它的栈帧是这样的：

1. 处理 Parent (HostComponent):

   • 创建 div#parent。
   • 进入子节点逻辑。
   • 此时 parentRef.current 指向 div#parent。
   • 递归结束，返回父级。

2. 处理 Child (HostComponent):

   • 创建 div#child。
   • 进入子节点逻辑。
   • 此时 childRef.current（假设存在）指向 div#child。
   • 递归结束，返回父级。

3. 处理 Grandchild (HostText):

   • 创建 span。
   • 递归结束。

为什么这个顺序很重要？

这就涉及到 React 的执行栈和闭包。completeWork 是一个递归函数。

function completeWork(current, workInProgress) {
  if (workInProgress.child) {
    // 递归调用
    // 这一层递归调用会先完成所有子节点，然后才返回
    workInProgress.child = completeWork(
      current?.child, 
      workInProgress.child
    );
  }

  // 只有当所有子节点都 completeWork 完毕后，才会执行下面的代码
  // 这时候，所有的 DOM 实例都已经存在于 instance 变量中了

  // 处理 Ref
  if (workInProgress.ref !== null) {
     // 此时，你可以放心大胆地访问 DOM
     const instance = workInProgress.stateNode;
     workInProgress.ref.current = instance;
  }
}

这种深度优先的递归，保证了子节点的 Ref 绑定一定先于父节点的 Ref 绑定完成。这对于很多嵌套的 DOM 操作（比如父节点想通过子节点的 Ref 做什么）是至关重要的时序保证。

第六部分：ForwardRef 与 Ref 的传递机制

在实际开发中，我们很少直接给组件写 ref，而是用 forwardRef。completeWork 是如何处理 forwardRef 的呢？

这是一个很有意思的机制。forwardRef 本质上是把父组件传进来的 ref prop，原封不动地转发给子组件的 ref prop。

当 completeWork 遍历到 forwardRef 组件时，它不会直接创建 DOM。它会查看这个组件的 ref 属性。如果这个组件本身暴露了 ref 属性（通过 forwardRef），React 就会把这个属性传递下去。

// forwardRef 源码简化逻辑
function forwardRef(render) {
  // 这是一个高阶组件，返回一个特殊的 Component
  return {
    render: (props, ref) => {
      // 注意：这里把 ref 传递给了子组件的 props
      return render(props, ref);
    }
  };
}

在 completeWork 阶段，React 的处理逻辑是：

1. 遇到 forwardRef 组件的 Fiber 节点。
2. 它发现这个组件有 ref prop（这是父组件传下来的）。
3. 它会把这个 ref 继续向下传递。
4. 最终，这个 ref 会被传递到最底层的 HostComponent（比如那个 <button>）。
5. 在底层的 completeWork 中，ref.current = buttonElement。
6. 但是，forwardRef 上的 ref 指针呢？React 会通过特殊的 Fiber 结构，把这个 ref 重新“绑定”回父级 forwardRef 组件的 stateNode 上（如果它有暴露 ref 的话）。

这就是为什么你可以这样写：

const FancyButton = React.forwardRef((props, ref) => (
  <button ref={ref} className="FancyButton">
    {props.children}
  </button>
));
// 你可以拿到 button 的 ref
const buttonRef = React.createRef();
<FancyButton ref={buttonRef} />

在 completeWork 阶段，React 就像是一个智能物流系统，把 buttonRef 这个包裹，精准地扔到了 <button> 的箱子里。

第七部分：Ref 的生命周期与 Fiber 的对应

我们再深入一点，ref 在 React 的 Fiber 节点结构中到底处于什么位置？

每个 Fiber 节点都有几个关键属性：

• memoizedProps: 组件渲染时的 props。
• memoizedState: 组件渲染时的 state。
• ref: 这是一个特殊的属性，它指向一个 ReactRef 对象。

// React 内部定义的 Ref 类型
// 这有点像 C++ 的指针，或者 Go 的接口
export type RefObject<T> = {
  current: T | null;
};

function completeWork(...) {
  // ...
  const ref = workInProgress.pendingProps.ref;

  if (ref !== null && typeof ref !== 'function') {
    // 如果 ref 是一个对象，我们需要确保它被正确设置
    // 在某些情况下，React 会将 ref 存储在 FiberNode 上，而不是直接引用外部对象
    // 但对于 useRef，它就是直接引用外部对象
    // 这涉及到 React 的内部优化，避免闭包问题
  }
  // ...
}

React 为了避免在渲染过程中直接修改外部对象导致不可预测的行为（虽然 React 保证渲染是纯函数，但 completeWork 是副作用处理），它使用了一种“引用追踪”机制。

当 completeWork 执行 ref.current = instance 时，它不仅仅是赋值。React 会检查这个 ref 对象是否已经在 fiber.ref 中注册过。

• 如果是第一次： React 会创建一个回调函数来监听 DOM 的变化，并把这个回调函数保存在 fiber.ref 中。
• 如果是更新： React 会直接更新 ref.current。

这种机制保证了 ref.current 始终与最新的 DOM 实例同步。当 DOM 节点被卸载时（unmount），React 会触发 ref 的回调（如果是函数式 ref），或者在对象式 ref 中将其置为 null。

第八部分：性能与异常处理

既然我们在 completeWork 阶段做了这么多的物理绑定操作，那么性能会不会受影响？

答案是：有影响，但这是必须的。

completeWork 阶段是同步的。对于 useRef，它的更新是同步的。这意味着，如果你在 completeWork 里给 ref.current 赋值，那么在下一次渲染（Render）之前，这个值就已经变了。

这带来了一些有趣的副作用：

1. 极速访问： 因为赋值发生在渲染阶段，所以在 useEffect 中读取 ref.current 时，你获取的永远是最新值（已经绑定了 DOM）。
2. 潜在的 Bug： 如果你试图在 completeWork 阶段（渲染期间）依赖 ref.current 的值来做逻辑判断，你可能会遇到闭包陷阱或者数据不一致的问题。因为 completeWork 遍历树的过程中，树的某些部分可能还没有完成绑定。

异常处理：

如果 completeWork 在创建 DOM 时出错了怎么办？或者 ref 的回调函数抛出异常了怎么办？
React 的错误边界机制和 try-catch 块在 commit 阶段会捕获这些错误。但在 completeWork 阶段，如果 ref 更新失败，React 可能会阻止整个渲染树的更新，并抛出一个致命错误，因为 DOM 结构的不一致性会导致整个应用崩溃。

第九部分：总结 – 从代码到物理世界

好了，我们爬过了这一大段源码。让我们来回味一下这个“物理绑定”的过程。

1. 蓝图绘制： React 根据 JSX 生成 Fiber 树。此时，一切都是虚拟的。
2. 工头进场： completeWork 开始遍历 Fiber 树。
3. 递归造物： 对于每一个 HostComponent，调用 createInstance，在浏览器世界里敲下 document.createElement，拿到物理世界的地址（instance）。
4. 指针指向： 在所有子节点处理完毕后，检查 ref。如果是 useRef 返回的对象，执行 ref.current = instance。
5. 契约达成： 此时，React 承诺的“虚拟组件”与浏览器实现的“物理 DOM”通过 ref.current 这个指针严丝合缝地连接在了一起。

这就是 React 的魔法。它隐藏了 DOM 操作的繁琐，用 completeWork 这种精密的调度，在看不见的地方默默完成了从抽象到具体的转化。

当你下次写下 const inputRef = useRef() 并在控制台打印它时，你可以骄傲地知道，在那个名为 completeWork 的隐秘角落，你的对象已经被赋予了生命，它正紧紧握着那个真实的 <input> 元素。

希望这篇文章能帮你彻底搞懂 useRef 的底层逻辑。这不仅仅是 API 的使用，更是理解 React 如何构建世界的钥匙。代码在左，源码在右，理性思考，尽情编码！