欢迎来到 React 的“后花园”：深度剖析 commitRoot 的三子相位执行流

各位老铁，大家好！

欢迎来到今天的“React 深度挖掘”大会。我是你们的老朋友，一个在 React 内部摸爬滚打多年的资深专家。今天我们不讲怎么写 useState，也不讲怎么封装一个好看的 UI 组件，我们要把镜头拉近，直接怼到 React 的“后花园”——Commit Phase（提交阶段）。

在 React 的世界里，工作分为两步走：渲染阶段 和 提交阶段。渲染阶段是“思考”，它很懒，喜欢切分任务，甚至可以被打断；而提交阶段是“行动”，它很勤奋，必须同步执行，一步都不能少。

今天的主角就是 commitRoot。这可不是个简单的函数，它就像一个指挥官，指挥着三个得力干将——Before Mutation、Mutation 和 Layout，共同完成从 Fiber 树到真实 DOM 的最终蜕变。

准备好了吗？让我们开始这场穿越 React 内部源码的冒险吧！

---

第一部分：开胃菜——为什么要分三个阶段？

在深入代码之前，咱们得先搞清楚这“三子相位”存在的意义。

想象一下，你是一个装修工长（React）。

1. 渲染阶段：你脑子里在想，客厅要刷成蓝色，把那个破旧的沙发扔掉，换一个真皮的。这是你的计划，你可以一边抽烟一边想，甚至可以想一半被打断去吃个饭。
2. 提交阶段：现在计划定好了，你拿着锤子进场了。

为什么不能“想”完一步直接“干”一步呢？因为 React 需要保证 DOM 的更新顺序。更重要的是，它需要处理那些“副作用”。

在 React 中，有些副作用（比如 useLayoutEffect）必须在浏览器绘制之前发生，而有些（比如 useEffect）则可以在浏览器绘制之后发生。为了照顾这些性格各异的副作用，React 把提交阶段拆成了三个小阶段。

好了，废话不多说，让我们看看 commitRoot 的核心代码骨架，感受一下那种“指挥若定”的气场：

function commitRoot(root) {
  // 1. 收尾工作，清理一些标记
  renderDidComplete();

  // 获取要提交的 Fiber 树
  const finishedWork = root.finishedWork;

  if (!finishedWork) {
    return null;
  }

  // 2. 重置根节点状态
  root.finishedWork = null;
  root.pendingCommitExpirationTime = NoWork;

  // -----------------------------------------------------------
  // 下面就是我们要重点讲的三子相位！
  // -----------------------------------------------------------

  // 第一阶段：Before Mutation
  // 处理那些需要在 DOM 变更前执行的副作用（主要是 useLayoutEffect）
  commitBeforeMutationEffects(root);

  // 第二阶段：Mutation
  // 真正的 DOM 变更！添加、删除、更新节点
  commitMutationEffects(root);

  // 第三阶段：Layout
  // DOM 变更后的布局计算，以及 useLayoutEffect 的第二次执行
  commitLayoutEffects(root);

  // -----------------------------------------------------------
  // 放手吧，副作用！
  // -----------------------------------------------------------

  // 执行那些可以在浏览器绘制后执行的副作用（useEffect）
  flushPassiveEffects();

  // 3. 结束
  root.current = finishedWork;
  flushSyncCallbacks(); // 执行同步回调

  return null;
}

看，这就是 commitRoot 的全貌。接下来，我们一个个 phase 过去，看看它们到底在干嘛。

---

第二部分：Before Mutation 阶段——化妆师与测量员

Phase Name: commitBeforeMutationEffects
核心任务： 处理 useLayoutEffect，进行布局测量。

这是第一个子相位。名字里的“Before Mutation”暗示了它发生在真正的 DOM 修改之前。这个阶段主要干两件事：测量尺寸 和 处理 useLayoutEffect。

1. 为什么叫“Before Mutation”？

因为在这个阶段，DOM 还没变！React 还没有去修改真实的 DOM 节点。那么，useLayoutEffect 是怎么工作的呢？

useLayoutEffect 是同步的。当你的组件渲染完成，React 准备提交时，它会立刻调用 useLayoutEffect 的回调函数。这意味着，在这个阶段，React 还没有把新树画到屏幕上，但是你的 useLayoutEffect 已经跑起来了。

2. 代码逻辑揭秘

React 怎么知道哪些组件需要执行 useLayoutEffect 呢？这得归功于 Fiber 树上的 flags（标志位）。

在渲染阶段，React 会给那些带有 useLayoutEffect 的 Fiber 节点打上 Update 或 Snapshot 标记。在 commitBeforeMutationEffects 中，React 会遍历这些节点。

// 伪代码演示 commitBeforeMutationEffects 的逻辑
function commitBeforeMutationEffects(root) {
  let firstEffect = root.firstEffect;
  let lastEffect = root.lastEffect;

  // 遍历 Effect List
  while (firstEffect !== null) {
    // 获取当前节点的 flags
    const nextEffect = firstEffect.nextEffect;

    // 如果有 Snapshot 标记（通常是 hydration 或者 useLayoutEffect 的第一次执行）
    if ((firstEffect.flags & Snapshot) !== NoFlags) {
      // 执行布局副作用
      commitBeforeMutationEffectOnFiber(firstEffect);
    }

    // 如果有 Update 标记（通常是 useLayoutEffect 的清理或更新）
    if ((firstEffect.flags & Update) !== NoFlags) {
      commitBeforeMutationEffectOnFiber(firstEffect);
    }

    firstEffect = nextEffect;
  }
}

3. 经典场景演示

这是 useLayoutEffect 的经典用例：获取 DOM 尺寸。

如果你直接在 useEffect 里获取 ref.current.offsetWidth，你会看到闪烁。因为 useEffect 是在 Mutation 阶段之后、浏览器绘制之前执行的，此时 DOM 已经变了，屏幕上已经渲染了新尺寸，然后瞬间变回旧尺寸，再变回新尺寸。这用户体验，简直想砸电脑。

但在 Before Mutation 阶段，DOM 还是旧的，还没有画上去。你可以放心地读取旧尺寸，进行计算，然后 React 会同步地应用新的样式。

import { useEffect, useRef, useLayoutEffect } from 'react';

function LayoutDemo() {
  const divRef = useRef(null);
  const [width, setWidth] = React.useState(0);

  // 这个 Effect 是同步的，在 DOM 更新前运行
  useLayoutEffect(() => {
    if (divRef.current) {
      const oldWidth = divRef.current.offsetWidth;
      console.log('Before Mutation: 旧宽度是', oldWidth);

      // 我们可以做计算，比如动态调整样式
      // 但不能直接修改 DOM，只能修改 state，让 React 去改
      const newWidth = oldWidth * 1.2; // 宽度增加 20%

      setWidth(newWidth);
    }
  }, []);

  // 这个 Effect 是异步的，在 Mutation 之后运行
  useEffect(() => {
    console.log('Mutation 之后: 准备绘制');
  });

  return (
    <div>
      <div 
        ref={divRef} 
        style={{ width: `${width}px`, height: '100px', background: 'red' }}
      >
        我是那个盒子
      </div>
    </div>
  );
}

在这个例子中，useLayoutEffect 就像一个测量员，在画布还没铺开之前，先量好尺寸，然后告诉 React：“嘿，把这个盒子变宽一点！” React 同步响应，直接修改 DOM，然后才把画布铺开。没有闪烁，只有流畅。

---

第三部分：Mutation 阶段——真正的“破坏”与“重建”

Phase Name: commitMutationEffects
核心任务： 真正的 DOM 变更（添加、删除、更新），执行 useEffect。

终于到了最激动人心的阶段了！名字里的 “Mutation” 听起来就很暴力，没错，这个阶段就是 DOM 的破坏与重建。

1. DOM 变更的三板斧

在 commitMutationEffects 中，React 会根据 Fiber 节点上的 flags 来决定怎么修改 DOM。主要有三种操作：

• Placement（插入）：节点是新加进来的。React 会调用 appendChild。
• Update（更新）：节点的属性变了（比如 className、style、text）。React 会调用 setAttribute 或 textContent。
• Deletion（删除）：节点被移除了。React 会调用 removeChild。

2. 源码中的遍历逻辑

这个阶段的核心逻辑在于 commitMutationEffectsOnFiber。React 会根据 fiber.flags 来分发任务。

// 伪代码演示 Mutation 逻辑
function commitMutationEffects(root) {
  let firstEffect = root.firstEffect;

  while (firstEffect !== null) {
    const nextEffect = firstEffect.nextEffect;

    // 1. 处理子节点
    commitMutationEffectsOnFiber(firstEffect);

    // 2. 处理副作用列表中的兄弟节点
    firstEffect = nextEffect;
  }
}

function commitMutationEffectsOnFiber(fiber) {
  const flags = fiber.flags;

  // --- 情况 A：节点被删除了 ---
  if (flags & Deletion) {
    commitDeletionEffects(fiber);
  }

  // --- 情况 B：节点被插入了 ---
  if (flags & Placement) {
    commitPlacement(fiber);
    fiber.flags &= ~Placement; // 清除标记
  }

  // --- 情况 C：节点属性更新了 ---
  if (flags & Update) {
    commitWork(fiber);
    fiber.flags &= ~Update;
  }
}

3. useEffect 的“大赦天下”

注意到了吗？useEffect 的执行并没有在这个阶段，而是在 flushPassiveEffects 中。为什么？

因为 useEffect 是异步的。如果在 Mutation 阶段同步执行 useEffect，那么整个 commitRoot 流程就会变成同步阻塞的。浏览器会被卡住，用户会感觉页面“卡顿”了一下。

所以，React 玩了个滑头：它先把 DOM 变好，然后把 useEffect 的回调函数收集起来，放在一个队列里。等 Mutation 阶段彻底结束，浏览器准备去重绘（Paint）的时候，React 才会悄悄地把 useEffect 的回调函数推入任务队列。

比喻：

• Before Mutation：测量员量尺寸。
• Mutation：装修工把墙刷了，把家具搬了。
• flushPassiveEffects (useEffect)：你在装修完之后，坐在沙发上发了个朋友圈，顺便清理一下装修垃圾。

4. 代码示例

这里我们用 useEffect 来演示 Mutation 阶段。

import { useState, useEffect } from 'react';

function MutationDemo() {
  const [show, setShow] = useState(true);

  useEffect(() => {
    console.log('useEffect 被触发了！我是在 Mutation 之后执行的。');
    // 这里可以访问到最新的 DOM 状态
    const element = document.getElementById('target');
    console.log('DOM 状态:', element ? element.innerText : '元素不存在');
  });

  return (
    <div>
      <button onClick={() => setShow(!show)}>
        {show ? '隐藏' : '显示'}
      </button>
      {show && <div id="target">我是被 Mutation 阶段创建的 DOM 节点</div>}
    </div>
  );
}

当你点击按钮时：

1. React 判定需要更新 DOM。
2. 进入 Mutation 阶段。React 发现需要删除 div#target，所以调用 removeChild。同时发现需要创建 div#target，所以调用 appendChild。
3. Mutation 阶段结束，DOM 树已经变了。
4. React 把 useEffect 的回调推入微任务队列。
5. 浏览器绘制。
6. useEffect 回调执行。

---

第四部分：Layout 阶段——最后的收尾与布局计算

Phase Name: commitLayoutEffects
核心任务： 处理 useLayoutEffect 的清理和第二次执行，计算布局。

这是最后一个子相位了。名字里的 “Layout” 指的是浏览器的重排。在 React 更新完 DOM 后，浏览器需要根据新的 DOM 计算布局，然后重绘。

1. 为什么叫 Layout？

因为在这个阶段，React 会执行一些需要依赖“布局计算结果”的操作。

还记得 useLayoutEffect 吗？在 Before Mutation 阶段，我们执行了 useLayoutEffect 的初始化。现在，在 Layout 阶段，React 会执行 useLayoutEffect 的清理和更新。

2. 执行顺序

Layout 阶段的执行顺序非常讲究，它是后进先出（LIFO）的。

为什么？因为 React 是从根节点往下遍历的。

• 根节点是先创建的。
• 子节点是后创建的。
• 但是，当组件卸载时，子节点必须先于父节点清理。

这就好比俄罗斯套娃，你打开外层的盒子（父节点），才能看到里面的盒子（子节点）。但当你把盒子收起来时，必须先收里面的。

3. 代码逻辑

function commitLayoutEffects(root) {
  let firstEffect = root.firstEffect;

  while (firstEffect !== null) {
    const nextEffect = firstEffect.nextEffect;

    // 处理 Layout 标记
    if ((firstEffect.flags & LayoutMask) !== NoFlags) {
      commitLayoutEffectOnFiber(firstEffect);
    }

    firstEffect = nextEffect;
  }
}

4. 代码示例

这个例子展示了 useLayoutEffect 的生命周期：挂载 -> 更新 -> 卸载（清理）。

import { useEffect, useLayoutEffect, useRef } from 'react';

function LayoutLifecycleDemo() {
  const countRef = useRef(0);

  // 模拟一个需要清理资源的操作
  useLayoutEffect(() => {
    console.log(`[Layout] 组件挂载/更新: count = ${countRef.current}`);

    // 返回一个清理函数
    return () => {
      console.log(`[Layout] 组件卸载/更新前清理: count = ${countRef.current}`);
    };
  }, []);

  // Mutation 阶段之后执行的 Effect
  useEffect(() => {
    console.log(`[Passive] useEffect 执行: count = ${countRef.current}`);
  });

  const handleClick = () => {
    countRef.current++;
  };

  return (
    <div>
      <button onClick={handleClick}>点击增加计数</button>
      <p>当前计数: {countRef.current}</p>
    </div>
  );
}

运行流程分析：

1. 组件第一次渲染。
2. Before Mutation: 执行 useLayoutEffect 初始化（输出 [Layout] 组件挂载）。
3. Mutation: DOM 更新（比如文本变了）。
4. Layout: 执行 useLayoutEffect 清理（因为还没卸载，所以是空的），然后执行更新（输出 [Layout] 组件挂载/更新）。注意：这里是更新，不是卸载！
5. Passive: useEffect 执行。

当你点击按钮增加计数时，流程再次触发，你会看到 [Layout] 的更新日志，紧接着是 [Passive] 的日志。

关键点： useLayoutEffect 的清理函数是在组件更新之前执行的。这意味着如果你在清理函数里做了某些操作，React 会把状态重置，然后再执行新的 useLayoutEffect。这种机制保证了状态的一致性。

---

第五部分：综合实战——一个完整的生命周期演示

为了彻底搞懂这三个阶段，我们来写一个稍微复杂一点的组件，它同时使用了 useLayoutEffect 和 useEffect，并且涉及 DOM 的添加和删除。

import { useState, useLayoutEffect, useEffect, useRef } from 'react';

function ComplexCommitDemo() {
  const [items, setItems] = useState(['Item 1']);
  const [isRemoving, setIsRemoving] = useState(false);
  const listRef = useRef(null);

  // 1. useLayoutEffect：同步获取宽度，确保布局正确
  useLayoutEffect(() => {
    console.log('--- Before Mutation 阶段：useLayoutEffect 执行 ---');
    if (listRef.current) {
      const width = listRef.current.offsetWidth;
      console.log(`测量到列表宽度: ${width}px`);
      // 这里可以做一些同步的 DOM 操作，比如强制设置样式
      listRef.current.style.border = '2px solid red';
    }
    return () => {
      console.log('Before Mutation 阶段：清理函数执行（重置样式）');
      if (listRef.current) {
        listRef.current.style.border = 'none';
      }
    };
  }, [items]);

  // 2. useEffect：异步副作用，DOM 已经变了
  useEffect(() => {
    console.log('--- Mutation 阶段后：useEffect 执行 ---');
    console.log('DOM 已经更新完毕，现在执行异步副作用');
    // 比如发送网络请求，或者打印 DOM 状态
  }, [items]);

  const addItem = () => {
    setItems([...items, `Item ${items.length + 1}`]);
  };

  const removeItem = () => {
    if (items.length > 0) {
      setItems(items.slice(0, -1));
    }
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Commit Phase 演示</h3>
      <button onClick={addItem}>添加项目</button>
      <button onClick={removeItem}>删除项目</button>

      {/* listRef 会被挂载到真实的 DOM 节点上 */}
      <ul ref={listRef} style={{ listStyle: 'none' }}>
        {items.map((item, index) => (
          <li key={index} style={{ margin: '10px 0' }}>
            {item}
          </li>
        ))}
      </ul>
    </div>
  );
}

让我们模拟一下点击“添加项目”时的控制台输出：

1. Before Mutation:
   • useLayoutEffect 执行。
   • 测量宽度（此时 DOM 还是旧的，没有新项）。
   • 设置红色边框。
2. Mutation:
   • React 发现需要插入新的 <li>。
   • 调用 appendChild。
   • 更新文本内容。
   • 移除红色边框（来自清理函数）。
3. Layout:
   • useLayoutEffect 再次执行（更新阶段）。
   • 测量宽度（此时 DOM 是新的，有新项）。
   • 设置红色边框。
4. Passive (useEffect):
   • 异步执行，打印“DOM 已经更新完毕”。

这个流程清晰地展示了 React 如何在同一个渲染周期内，利用三个不同的阶段来处理不同优先级和不同时机的副作用。

---

第六部分：性能优化与避坑指南

作为资深专家，我必须提醒大家，这三个阶段虽然强大，但用不好也会翻车。

1. 不要在 useLayoutEffect 里做耗时操作

useLayoutEffect 是同步的。如果在 Before Mutation 阶段，你的代码跑了一个 100ms 的循环，那么用户会看到白屏整整 100ms，然后页面突然闪变。这比 useEffect 闪烁还要糟糕，因为用户根本看不到过渡过程。

黄金法则： useLayoutEffect 里的代码必须尽可能快，只做简单的 DOM 读取和状态更新。

2. useEffect 的依赖陷阱

在 Mutation 阶段之后执行 useEffect，虽然给了浏览器绘制的机会，但也意味着你在 useEffect 里拿到的 DOM 状态是最新的。这很好，但要注意，如果你在 useEffect 里修改了 DOM（比如手动操作 class），React 可能会覆盖你的操作，除非你非常小心地处理。

3. 为什么 commitRoot 必须是同步的？

这是 React 的核心设计理念。渲染阶段是可中断的（为了不卡死 UI），但提交阶段必须是原子的。一旦开始提交，就必须一口气把所有 DOM 变更、所有 useLayoutEffect 都干完，然后才能交给浏览器去绘制。如果提交阶段被打断，DOM 状态就会不一致（比如一部分变了，一部分没变），导致严重的 Bug。

---

第七部分：源码层面的“最后一公里”

最后，让我们再看看 commitRoot 的结尾部分，这是整个流程的收网。

// commitRoot 函数的结尾
function commitRoot(root) {
  // ... 执行三个子阶段 ...

  // 1. 将 finishedWork 指向 current
  root.current = finishedWork;

  // 2. 执行同步回调
  flushSyncCallbacks();

  // 3. 执行被动副作用 (useEffect)
  flushPassiveEffects();

  // 4. 结束渲染，调度下一次渲染
  // 注意：这里会检查是否有新的更新，如果有，可能会再次触发 scheduleWork
  // 但在同一个 tick 内，React 不会立即重新进入 commitRoot，而是进入 render phase
  if (root.pendingExpirationTime > NoWork) {
    // ...
  }

  return null;
}

可以看到，commitRoot 执行完后，React 会检查是否有新的任务（比如用户又点了一次按钮）。如果有，它会再次进入 scheduleWork -> renderRoot -> commitRoot。这就是 React 的“Reconciliation（协调）”过程。

---

总结

好了，各位老铁，我们的“React commitRoot 三子相位”讲座到这里就接近尾声了。

我们回顾一下今天的内容：

1. Before Mutation：测量员，处理 useLayoutEffect，同步，在 DOM 变更前。
2. Mutation：破坏者，真正的 DOM 变更（增删改），处理 useEffect 入队，异步。
3. Layout：收尾员，处理 useLayoutEffect 的清理和更新，计算布局。

这三个阶段就像是一支配合默契的交响乐团：

• Before Mutation 是指挥家挥动指挥棒前的准备；
• Mutation 是乐手们吹响号角，奏响乐曲；
• Layout 是乐曲的结尾和定音。

理解了这三个阶段，你就真正理解了 React 是如何把虚拟的 Fiber 树变成屏幕上真实可见的 DOM 的。这不仅仅是写代码，这是在理解计算机图形学和状态管理的艺术。

希望这篇文章能让你对 React 的内部机制有更深刻的理解。下次当你写 useLayoutEffect 感到心慌，或者对 useEffect 的时机感到困惑时，记得回来看看这三个 Phase。

我是你们的资深专家，咱们下期再见！