三个公式 — React 到底是什么

Three formulas — what React really is

UI = f(state) · diff(prev, next) · schedule(work)

UI = f(state) · diff(prev, next) · schedule(work)

公式①：声明式的代价

Formula ①: the price of declarative

React 的祖传卖点是声明式——你说"长这样"，它去搞定"怎么变成这样"。代价是：每次状态变了，理论上需要把整棵 UI 重新算一遍。这条公式只关心"正确性"——和最终 DOM 应该长什么样。它不解决性能，那是公式②要做的事。

React's lineage sells declarative: you say what it looks like, React figures out how to get there. The cost: every state change theoretically re-evaluates the entire UI. This formula is about correctness, not performance — that's what formula ② is for.

公式②：diff 不是 vDOM

Formula ②: diff is not vDOM

很多人把"虚拟 DOM"和"diff"画等号——这是个误会。虚拟 DOM 只是一种表示（JS 对象描述 UI 树），diff 才是算法。React 16 之后这个算法跑在 Fiber 之上，已经不能简单叫"diff"了——它是一棵链表化的树 + 可中断的递归 + effect 收集。但公式仍然成立：你要的是最小变更集合。

People often equate "virtual DOM" with "diff" — they aren't. vDOM is a representation (JS objects describing the UI tree); diff is the algorithm. After React 16, the algorithm runs over Fiber, which is more than just diff: a linked-list-tree + interruptible recursion + effect collection. The formula still holds though: the goal is the minimal patch set.

公式③：调度才是 React 17+ 真正的革命

Formula ③: scheduling is the real React 17+ revolution

公式①和②自 2013 年就有了。真正让 React 16 → 18 重写一遍的是公式③：同一个任务的不同部分可以有不同优先级。一次setState 触发的 render 不再是"一口气跑完"——它会被切片、被打断、被丢弃、被重排，然后再继续。这就是 Concurrent Mode 的本质。

Formulas ① and ② have been here since 2013. What forced the full rewrite from React 16 → 18 was ③: different parts of the same task may have different priorities. A render triggered by setState is no longer "one shot, run to completion" — it can be sliced, interrupted, discarded, reordered. That is Concurrent Mode.

家谱 — React 的 13 年

A family tree — 13 years of React

从 Jordan Walke 的内部 hack 到 RSC 的标准化

From Jordan Walke's internal hack to the RSC standard

五次分裂

Five forks

为何重写 — Stack Reconciler 的死结

The rewrite — why Stack had to die

递归不可中断 · 浏览器卡顿 · Andrew Clark 的两年

Recursion can't pause · jank · Andrew Clark's two years

死结的样子

The deadlock

重写的代价

The cost of rewrite

Andrew Clark（现 Vercel）2015 年开始独立做 Fiber——一开始叫 "ReactFiber"，作为实验分支跑了两年。这段时间他写下了 React 史上最重要的代码注释，至今仍在 ReactFiberBeginWork.js 顶部：

Andrew Clark (now at Vercel) started Fiber solo in 2015. The branch ran as an "experiment" for two years. In that time he wrote the most important comment in React's history — still at the top of ReactFiberBeginWork.js:

// This is the function where most of the work happens.
// We will reach into the WorkInProgress fiber, render its children,
// and return the next unit of work to be performed.
function beginWork(current, workInProgress, renderLanes) {
  // ... 2,500 lines of switch(fiber.tag) ...
}

两年里他重写了三次。React 16.0 在 2017 年 9 月 26 日发布——发布那天 GitHub issue 上排着 1500 个等待迁移的项目。但API 完全没变。这就是 Andrew 在 React Conf 2017 talk 里说的那句话："我们换了引擎，但你不需要换驾照。"

Three full rewrites in two years. React 16.0 shipped September 26, 2017 — 1500 projects queued up to migrate on launch day. But the public API didn't change. As Andrew put it at React Conf 2017: "We changed the engine, you don't need a new driver's license."

三层架构 — core / reconciler / renderer

Three layers — core / reconciler / renderer

为什么同一套 React 能同时跑在 DOM、Native、Three.js 上

how one React runs on DOM, Native, Three.js — all at once

HostConfig — 三层之间唯一的合同

HostConfig — the only contract between layers

Reconciler 完全不知道自己驱动的是什么——它只调用 HostConfig 上的方法。想做一个新的 renderer？实现这张表就行（节选）：

The reconciler has no idea what it's driving — it just calls methods on the HostConfig. Want a new renderer? Implement this table (excerpt):

// react-reconciler/src/ReactFiberHostConfig.js · contract
interface HostConfig<Type, Props, Container, Instance, ...> {
  // — 创建/插入/更新/删除
  createInstance(type, props, root, ctx, fiber): Instance;
  createTextInstance(text, root, ctx, fiber): TextInstance;
  appendInitialChild(parent, child): void;
  appendChild(parent, child): void;
  insertBefore(parent, child, before): void;
  removeChild(parent, child): void;
  commitUpdate(inst, payload, type, oldP, newP): void;

  // — 调度接入
  scheduleTimeout(fn, delay): TimeoutID;
  cancelTimeout(id): void;
  noTimeout: -1;
  supportsMicrotasks: boolean;

  // — 平台行为
  supportsMutation: boolean;   // DOM = true
  supportsPersistence: boolean; // Fabric = true (immutable trees)
  supportsHydration: boolean;   // SSR
}

流水线全景 — render · commit · scheduler

Pipeline overview — render · commit · scheduler

一张图把 13 步串起来

all 13 stages in one diagram

三个阶段的边界条件

Boundary conditions of the three phases

The Counter — 一段贯穿全文的例子

The Counter — the through-line

9 行代码 · 一次点击 · 13 步流水线

9 lines · one click · 13 stages

// Counter.jsx — our specimen for the rest of this article
import { useState, useEffect } from 'react';

function Counter() {
  const [count, setCount] = useState(0);
  useEffect(() => { document.title = `#${count}`; }, [count]);

  return (
    <div className="counter">
      <h1>Count: {count}</h1>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </div>
  );
}

Counter 的一生 · 四幕

The four acts of Counter

为了让接下来 13 章的 SPECIMEN 卡片有同一条时间线，把 Counter 这个标本切成四个时间点。每一章会在其末尾的 SPECIMEN 卡片上注明它讨论的是哪一幕——这样你既能纵向看"原理"，也能横向看"Counter 此刻活成什么样"。

To give the SPECIMEN cards a single shared timeline, the Counter's life is sliced into four moments. Each chapter's specimen card labels which act it captures — so you can read down for theory, and across for what the Counter looks like right now.

第一击的时间线 · ACT II 详解

Timeline of ACT II — the first click

用户点击按钮。React 19 在约 1.2 ms内跑完这整套流水线（在 M2 MacBook + Chrome 130 上的实测中位数）。下面这张图把每一步对应到具体时间：

User clicks. React 19 runs the full pipeline in ~1.2 ms (median on M2 MacBook + Chrome 130). Here's each step against the clock:

Counter 长大 — 从 Ch10 起多出一个 TodoList 子组件

Counter grows up — adopts a TodoList child from Ch10 onward

上面那段 Counter 是同一个标本的最简形态。但 React 里有些路径——keyed list diff、useContext 传播、useTransition 降优先级、Suspense throw promise、RSC + Server Action——必须有≥ 2 层组件 + 列表 + 异步才会激活。所以从 Ch10 起,Counter 多出一个 TodoList 子组件(4 行代码)。名字不变,标本不换——同一棵 Fiber 树长出几片新叶子。每一章的 SPECIMEN 卡上会标 v1 (简版 5 fibers) 还是 v2 (含 TodoList 50+ fibers),你随时知道现在站在哪一帧。

The Counter above is the simplest form of one and the same specimen. But some React paths — keyed list diff, useContext propagation, useTransition demotion, Suspense throws, RSC + Server Action — only light up when you have ≥ 2 component levels + a list + async. So from Ch10 onward, Counter grows a TodoList child (4 extra lines). Same name, same specimen — a single Fiber tree sprouting more leaves. Each chapter's SPECIMEN card labels which version it captures: v1 (5 fibers) or v2 (with TodoList, 50+ fibers). You always know which frame you're standing in.

// Counter.jsx — v2 · same component, one new child & one Suspense wrapper
import { useState, useEffect, useTransition, useContext, use, Suspense } from 'react';
import { ThemeContext } from './contexts';
import { addTodoAction } from './actions';       // Server Action — appears only from Ch20

function Counter({ todosPromise }) {
  const theme = useContext(ThemeContext);                  // ← Ch12B context propagation
  const [count, setCount] = useState(0);
  const [filter, setFilter] = useState('all');              // ← new in v2
  const [pending, startTransition] = useTransition();        // ← Ch17 demotion path
  useEffect(() => { document.title = `#${count}`; }, [count]);

  return (
    <div className={`counter counter--${theme}`}>
      <h1>Count: {count}</h1>
      <button onClick={() => setCount(count + 1)}>+1</button>

      /* TodoList child below — same Counter, more leaves */
      <Suspense fallback={<p>loading…</p>}>
        <TodoList todosPromise={todosPromise} filter={filter} setFilter={(f) => startTransition(() => setFilter(f))} />
      </Suspense>
    </div>
  );
}

// TodoList — pure child, lights up list-diff + Suspense + Server Action paths
function TodoList({ todosPromise, filter, setFilter }) {
  const todos = use(todosPromise);                // ← Ch18 throws if pending
  const visible = filter === 'all' ? todos : todos.filter(t => t.status === filter);

  return <ul>
    {visible.map(t => <li key={t.id}>{t.text}</li>)}    /* ← Ch10 keyed-list diff path */
    <form action={addTodoAction}><input name="text" /></form>  /* ← Ch21 Action */
  </ul>;
}

JSX → React Element — 编译期就完成的一步

JSX → React Element — done at compile time

jsx() 不是 createElement · 不是 vDOM 的等价物

jsx() is not createElement; it is not the virtual DOM

JSX 是个语法，不是运行时。它在编译期就被转写为函数调用——React 17 之前是 React.createElement(...)，17 之后是 react/jsx-runtime 里的 jsx() / jsxs()。前者每次调用都查 React 这个全局变量；后者直接 import，体积更小、可以做 dev-only 检查。我们的 Counter 编译后长这样：

JSX is syntax, not runtime. The compiler rewrites it to function calls — React.createElement(...) before React 17, jsx() / jsxs() from react/jsx-runtime after. The latter is imported directly, smaller, with dev-only checks. Our Counter compiles to:

// after babel @babel/preset-react · 'automatic' runtime
import { jsx as _jsx, jsxs as _jsxs } from 'react/jsx-runtime';

function Counter() {
  const [count, setCount] = useState(0);
  useEffect(() => { document.title = `#${count}`; }, [count]);

  return _jsxs("div", {
    className: "counter",
    children: [
      _jsx("h1", { children: ["Count: ", count] }),
      _jsx("button", {
        onClick: () => setCount(count + 1),
        children: "+1"
      })
    ]
  });
}

Element 长什么样

What an Element actually is

_jsx() 返回的不是 DOM 节点，是一个普通 JS 对象——React 把它称作 Element。Element 是 React 整个体系里唯一你能直接看见的数据结构：

_jsx() doesn't return a DOM node — it returns a plain JS object React calls an Element. Elements are the only data structure in React you ever directly handle:

// the actual shape — react/src/ReactElement.js
{
  $$typeof: Symbol(react.element),  // 防 XSS · JSON 序列化不能复刻
  type: "div",                  // host string · or function component · or class
  key: null,
  ref: null,
  props: {
    className: "counter",
    children: [ /* nested Elements */ ]
  },
  _owner: null                    // dev only · debug helper
}

Element 是不变的快照

Elements are immutable snapshots

每次 render，Counter() 都返回全新的 Element 对象。Element 是不可变的——它只描述"此刻 UI 应该是什么样"，不持有状态、不持有 DOM 引用。状态和 DOM 引用都活在下一章要讲的 Fiber 节点上。

Every render, Counter() returns fresh Elements. They are immutable — they describe what the UI should look like right now. State and DOM refs live on the Fiber nodes (next chapter).

很多博客文章把 Element 称作 "vDOM 节点"——技术上没错，但容易让人以为 React 在内存里维护着一棵 vDOM 树。没有这棵树。React 只有：（a）你刚刚 return 出来的 Element 们，（b）一棵 Fiber 树。Element 用完就丢，Fiber 才是常驻的"虚拟世界"。

Many articles call Elements "vDOM nodes" — technically true, misleading in practice. People imagine React keeps a "vDOM tree" in memory. It doesn't. React holds (a) the Elements you just returned and (b) a Fiber tree. Elements are throwaway. Fibers are the persistent "virtual world".

Fiber 节点 — 链表化的树

Fiber node — a tree as a linked list

child · sibling · return —— 三根指针撑起 React 半壁江山

child · sibling · return —— three pointers, half of React

Fiber 是 React 16 引入的底层数据结构——名字来自 OS 的"纤程"：比线程更轻、可协作调度的执行单元。每个 React 组件实例对应一个 Fiber 节点，每个原生 DOM 元素也对应一个 Fiber 节点。这些节点不是普通的树——它们用链表连起来。

Fiber is the data structure React 16 introduced — name borrowed from OS-level fibers (lighter than threads, cooperatively scheduled). Each component instance maps to one Fiber. So does each host DOM element. They aren't a normal tree — they're connected by linked-list pointers.

三根指针构成一棵树

Three pointers make a tree

Fiber 字段地图

Field map of a Fiber

React 19 的 Fiber 类约有 60 个字段，按用途可以分成四簇——这是它能同时承担结构、状态、调度、提交四件事的根因：

A React 19 Fiber has ~60 fields, grouped into four clusters — it's how one struct can carry structure, state, scheduling, commit info all at once:

// react-reconciler/src/ReactFiber.js · simplified
type Fiber = {
  // ────── ① 结构 · 链表树
  tag: WorkTag,          // 0 = FunctionComponent, 5 = HostComponent, 13 = Suspense...
  key: null | string,
  type: any,              // "div" | Counter | Suspense ...
  stateNode: any,         // 真实 DOM 节点（HostComponent）/ class 实例（ClassComponent）
  child: Fiber | null,    // 第一个子
  sibling: Fiber | null,  // 下一个兄弟
  return: Fiber | null,   // 父 (注意：不叫 parent!)

  // ────── ② 状态 · 此次 render 的输入输出
  pendingProps: any,       // 这次要 render 的 props
  memoizedProps: any,      // 上一次提交时的 props
  memoizedState: any,      // hooks 链表头（function comp）
  updateQueue: any,        // 未处理的 setState 队列

  // ────── ③ 调度 · 这棵子树的优先级
  lanes: Lanes,           // 自己有更新的 lanes（位掩码）
  childLanes: Lanes,      // 子孙有更新的 lanes（剪枝用）

  // ────── ④ 提交 · 给 commit phase 的清单
  flags: Flags,           // Placement / Update / Deletion / Snapshot ...
  subtreeFlags: Flags,    // 子孙是否有 flags（剪枝用）
  deletions: Array<Fiber>,
  alternate: Fiber | null // 双缓冲的另一棵 (下一章)
};

Tag 全家谱 — 28 种 Fiber 类型

Tag family tree — 28 Fiber types

前面的代码里 tag 我们只举了 FunctionComponent (0) 和 HostComponent (5) 两种。但 WorkTag 这个 enum 一共有 28 个值（React 19 起）——每一个都对应 beginWork 里 switch 语句的一个 case。理解每个 tag 在干什么，比起背 hooks API 还能让你更"看穿" React。

In earlier code we only mentioned FunctionComponent (0) and HostComponent (5). But the WorkTag enum has 28 values (as of React 19) — each one is a case in beginWork's switch. Knowing what each tag does is, frankly, more "X-ray" than memorizing the hooks API.

▸ 你直接写的

▸ Components you write

▸ 宿主元素（DOM / Native）

▸ Host elements (DOM / Native)

▸ 控制流 / 边界

▸ Control flow / boundaries

▸ Context · 性能 · 调度

▸ Context · perf · scheduling

▸ 内部 / 过渡态 / 几乎用不到

▸ Internal / transient / rarely seen

双缓冲 — current 与 workInProgress

Double buffer — current vs workInProgress

显卡借来的把戏 · alternate 指针 · 失败回滚

borrowed from GPUs · the alternate pointer · safe rollback

游戏引擎渲染时永远维护两块帧缓冲——front buffer 给屏幕看，back buffer 慢慢画。画完了把指针一换，眨眼之间。React Fiber 借了同样的把戏：内存里同时存两棵 Fiber 树——current（已经在屏幕上）和 workInProgress（正在重新计算）。它们通过 fiber.alternate 互相指向。

Game engines keep two frame buffers — front (shown) and back (drawn into). Swap the pointer when done. React Fiber stole the trick: two Fiber trees live simultaneously — current (on screen) and workInProgress (being recomputed). Linked by fiber.alternate.

为什么要这样设计

Why this design

commit 那一刻 — 单个指令完成翻转

The moment of commit — a single-instruction flip

"双缓冲翻转"听起来很玄, 其实它只是一行赋值。React 在 commitMutationEffectsOnFiber 把所有 DOM 改完之后, 跑这一句:

"Double-buffer flip" sounds dramatic; in reality it's one assignment. After commitMutationEffectsOnFiber has applied all DOM mutations, React runs this single line:

// react-reconciler/src/ReactFiberWorkLoop.js · commitRootImpl()
// before this line:  root.current = oldFiberTree  (the one user is staring at)
// after this line:   root.current = newFiberTree  (the one we just built)
root.current = finishedWork;
// — and that's it. The "new screen" is now the source of truth.

这条赋值之前: oldRoot 还在屏幕上,finishedWork 是新的 wip。之后: 它们的身份完全交换——上一帧的 oldRoot 从 "current" 退役成"alternate", 下一次更新会从它身上抠节点出来当 wip 用。React 没有任何"tree merge"操作, 没有"diff apply"操作——commit 的本质就是把 root.current 指向另一棵树。下面这张图把这"一帧之内的指针翻转"拆出来给你看:

Before this line: oldRoot is still on screen, finishedWork is the wip. After: their identities swap completely — last frame's oldRoot retires from "current" to "alternate", and the next update will recycle nodes off it for wip. There is no "tree merge" or "diff apply" — commit's essence is simply pointing root.current at the other tree. This figure unpacks the "pointer flip within one frame":

bail-out 时 — wip 节点根本不分配

On bail-out — no wip node is allocated at all

教学时常把双缓冲讲成"每次 render 都铺一棵完整的 wip 树"——这是错的。React 的 reconciler 对每一个 fiber 都要先问: "这棵子树要不要重渲?" 答案是"不"时, 它就跳过 wip 分配, 直接复用 current 节点。这是 bailoutOnAlreadyFinishedWork 干的活, 在 beginWork 入口就被检查。

A common teaching error: "every render allocates a full wip tree." Wrong. The reconciler asks for each fiber: "does this subtree need a fresh render?" When the answer is no, it skips wip allocation entirely and reuses the current node. This is what bailoutOnAlreadyFinishedWork does, checked at beginWork's entry.

useState 第二次读 — 走的是 current 还是 wip?

useState's second read — does it walk current or wip?

教学上,大家都会画"useState 链表"——每个 hook 一个节点, 用 next 串起来。但很少有人讲: render 中读 hook 时走的是 wip 链表, commit 之后所有 read 都走 current 链表。这两条链表通过 fiber.alternate.memoizedState 互指——结构同构, 但内容可能不同(wip 链表里是新值, current 链表里是旧值)。

Everyone draws the "useState linked list" — one node per hook, threaded by next. Rarely explained: during render the read walks the wip list; after commit, every read walks the current list. The two lists mirror each other via fiber.alternate.memoizedState — isomorphic in shape, possibly different in content (wip holds the new value, current holds the old).

beginWork — 递的那一半

beginWork — the descent half

workLoop · performUnitOfWork · 一个组件一次循环

workLoop · performUnitOfWork · one component, one iteration

Render Phase 的主循环叫 workLoopSync / workLoopConcurrent。它不是递归——是个 while 循环。每一轮处理一个 Fiber 节点，分两步：beginWork（递）把子 Element 转成子 Fiber，completeWork（归，下一章）收集 effects。

The render-phase main loop is workLoopSync / workLoopConcurrent. Not recursion — a while loop. Each iteration handles one Fiber in two halves: beginWork (descent) turns child Elements into child Fibers; completeWork (ascent, next chapter) collects effects.

// ReactFiberWorkLoop.js · the real loop
function workLoopConcurrent() {
  while (workInProgress !== null && !shouldYield()) {
    performUnitOfWork(workInProgress);
  }
}

function performUnitOfWork(unitOfWork) {
  const current = unitOfWork.alternate;
  const next = beginWork(current, unitOfWork, renderLanes);

  unitOfWork.memoizedProps = unitOfWork.pendingProps;
  if (next === null) {
    completeUnitOfWork(unitOfWork);  // 没有 child → 归
  } else {
    workInProgress = next;             // 有 child → 继续递
  }
}

beginWork 的 switch

beginWork's switch

beginWork 进来第一件事就是看 fiber.tag——根据是函数组件、类组件、host 元素、Suspense、Memo……分发到不同处理函数。这就是为什么 React 源码里有那么多 updateXxx 函数：

First thing beginWork does: dispatch on fiber.tag — function vs class vs host element vs Suspense vs Memo… That's why React's source has so many updateXxx functions:

function beginWork(current, workInProgress, renderLanes) {
  // — bail-out 优化：props 没变 + 子树没更新 → 整个子树复用
  if (current !== null && oldProps === newProps && !hasContextChanged()) {
    if (!includesSomeLane(renderLanes, workInProgress.lanes)) {
      return bailoutOnAlreadyFinishedWork(...);  // 直接跳过
    }
  }

  switch (workInProgress.tag) {
    case FunctionComponent: return updateFunctionComponent(...);
    case ClassComponent:    return updateClassComponent(...);
    case HostComponent:     return updateHostComponent(...);
    case HostText:          return updateHostText(...);
    case SuspenseComponent: return updateSuspenseComponent(...);
    case MemoComponent:     return updateMemoComponent(...);
    // ... 30 more cases ...
  }
}

function updateFunctionComponent(current, wip, Comp, nextProps, renderLanes) {
  // ★ 整个函数体执行就在这一行：
  const nextChildren = renderWithHooks(current, wip, Comp, nextProps, ...);
  // ↑ Counter() 在这里被实际调用，hooks 在这里取值

  reconcileChildren(current, wip, nextChildren, renderLanes);  // 下一章
  return wip.child;
}

bail-out — 性能优化的灵魂

bail-out — the soul of performance

注意 beginWork 第一行的提前返回：如果 props 没变、context 没变、这棵子树没有任何 update lane——React 整棵子树都跳过。这就是 React.memo、useMemo、useCallback 起作用的位置。它们不是"缓存"，是把 oldProps === newProps 这条件做真。

Note the early return at the top of beginWork: if props are stable, context didn't change, and the subtree has no pending lane — React skips the whole subtree. This is where React.memo, useMemo, useCallback earn their keep. They aren't "caching" — they're making oldProps === newProps become true.

Reconciliation — O(n) diff 的三个赌注

Reconciliation — three bets behind O(n) diff

同层比较 · type 标识 · key 标识

same-level · type identity · key identity

通用的两棵树之间最小编辑距离是 O(n³) 问题——n 是节点数。React 把它压到 O(n)。代价是放弃最优解，转而依赖三个工程上的赌注：

The general "minimum edit distance between two trees" is O(n³) where n is the number of nodes. React drops it to O(n) by giving up optimality and betting on three pragmatic heuristics:

单子节点 · 多子节点

Single child · multi-child

React 的 reconcile 算法分两条主路径：单子节点（reconcileSingleElement）和多子节点（reconcileChildrenArray）。前者简单，后者复杂——尤其当数组元素带 key 时。

Two main paths: single child (reconcileSingleElement) and array (reconcileChildrenArray). Single is trivial; arrays — especially keyed arrays — are where the complexity lives.

lastPlacedIndex · 决定谁要"真的移动"的贪心算法

lastPlacedIndex · the greedy heuristic that picks who actually moves

前一节的算法告诉你哪些 fiber 可以复用，但还没说哪些要真的在 DOM 里挪位置。复用了不等于不挪——位置变了仍需 insertBefore。React 用一个极简贪心算法决定"谁挪、谁站着"：维护一个游标 lastPlacedIndex，对每个新位置上能复用的 fiber，看它在旧列表里的位置——只有逆向的才打 Placement。这个算法不是最优，但它是 O(n)、无需排序。

The previous step tells you which fibers can be reused, but not which ones need to physically move in the DOM. Reuse ≠ stay-in-place — if its slot changes, insertBefore still has to run. React uses a tiny greedy heuristic: keep a cursor lastPlacedIndex; for each reused fiber, check its position in the old list — only backwards ones get a Placement flag. Not optimal, but O(n) with no sort.

// react-reconciler/src/ReactChildFiber.js · simplified
function placeChild(newFiber, lastPlacedIndex, newIndex) {
  newFiber.index = newIndex;
  const current = newFiber.alternate;
  if (current === null) {
    newFiber.flags |= Placement;          // 新建的, 一定要 Placement
    return lastPlacedIndex;
  }
  const oldIndex = current.index;
  if (oldIndex < lastPlacedIndex) {
    newFiber.flags |= Placement;          // ★ 逆向 → 需要移动
    return lastPlacedIndex;
  } else {
    return oldIndex;                     // 顺向 → 不动, cursor 推进
  }
}

key 错了，代价巨大

Wrong key, huge cost

completeWork — 归的那一半

completeWork — the ascent half

effect flags · subtreeFlags · 离屏 DOM 创建

effect flags · subtreeFlags · off-DOM creation

当 workLoop 走到一个没有 child 的 Fiber（叶子）或它的 child 已经完成，它进入 completeUnitOfWork——这是"归"。归阶段做三件事：

When workLoop reaches a Fiber whose children are all done (or a leaf), it enters completeUnitOfWork — "ascent". Ascent does three things:

Effect Flags · 一个位字段说尽一切

Effect Flags · a bitmask says it all

每个 Fiber 节点的 flags 是个 32 位的位字段——一位代表一种"commit 阶段要做的事"。位运算极快，而且容易合并：

flags on every Fiber is a 32-bit bitmask — one bit per "thing to do in commit". Bitwise ops are fast and trivially combine:

// react-reconciler/src/ReactFiberFlags.js · the bitmask
export const NoFlags        = 0b00000000000000000000000000;
export const Placement     = 0b00000000000000000000000010; // 插入到 DOM
export const Update        = 0b00000000000000000000000100; // 更新属性
export const ChildDeletion = 0b00000000000000000000010000; // 子节点要删
export const ContentReset  = 0b00000000000000000000100000;
export const Callback      = 0b00000000000000000001000000;
export const Ref           = 0b00000000000000001000000000; // 要调 ref callback
export const Snapshot      = 0b00000000000000010000000000; // getSnapshotBeforeUpdate
export const Passive       = 0b00000000000000100000000000; // useEffect
export const StoreConsistency = 0b00000000000001000000000000; // useSyncExternalStore
export const LayoutMask = Update | Callback | Ref | Visibility;
export const PassiveMask = Passive | Visibility | ChildDeletion;

render phase 结束

End of render phase

当 workLoop 归到 HostRoot——render phase 结束。此时内存里有一棵完整的 workInProgress Fiber 树，每个节点上挂着 flags / updatePayload，subtreeFlags 在父节点上做了"这棵子树有没有事"的总结。下一步：commit。

When workLoop ascends back to HostRoot — render phase is done. In memory: a complete workInProgress Fiber tree, each node carrying flags / updatePayload, subtreeFlags summarising "does this subtree have work". Next: commit.

Hooks 内核 — 链表与 dispatcher

Hooks core — linked list & dispatcher

memoizedState · queue · 调用顺序的物理约束

memoizedState · queue · call-order as a physical constraint

函数组件没有 this，也没有持久化的实例——它只是个函数，跑完就丢。那 useState 拿到的值是从哪里来的？答案在两行代码里：

Function components have no this, no persistent instance — they're functions that run and vanish. So where does useState read its value? Two lines tell the story:

// react-reconciler/src/ReactFiberHooks.js · simplified
let currentlyRenderingFiber: Fiber;        // 当前在 render 谁
let workInProgressHook: Hook | null;     // 链表游标

function renderWithHooks(current, wip, Component, props, ...) {
  currentlyRenderingFiber = wip;
  wip.memoizedState = null;
  wip.updateQueue = null;
  workInProgressHook = null;
  ReactCurrentDispatcher.current = mount ? HooksOnMount : HooksOnUpdate;

  const children = Component(props);  // ★ 用户的 Counter() 被调用

  ReactCurrentDispatcher.current = ContextOnlyDispatcher;
  return children;
}

Counter() 里调 useState(0)，实际上调的是 ReactCurrentDispatcher.current.useState——这是挂在全局变量上的指针。挂载时指向 mountState，更新时指向 updateState。两个版本做的事完全不同。

When Counter() calls useState(0), it actually calls ReactCurrentDispatcher.current.useState — a pointer on a module-level variable. On mount it points to mountState; on update to updateState. Different implementations entirely.

Hooks 在 Fiber 上的形态

Hooks on the Fiber

"hooks 调用顺序"规则的真正原因

Why "rules of hooks" exist

React 用调用顺序来对齐 hooks——第一次 useState 拿链表第一节点，第二次 useState 拿第二节点。没有 ID，没有名字。 这就是为什么 if (...) useState(...) 会让 React 整个崩——条件分支会让链表对不上。这条规则不是约定，是 React 16.8 这套设计的物理约束。

React aligns hooks by call order — first useState reads the first node, second reads the second. No IDs, no names. That's why if (...) useState(...) breaks everything — conditional branches misalign the list. This isn't a convention — it's a physical constraint of the React 16.8 design.

setState 的真实路径

The real path of setState

// setCount(1) actually goes through here:
function dispatchSetState(fiber, queue, action) {
  // ① 用调度器算出 lane（更新优先级）
  const lane = requestUpdateLane(fiber);

  // ② 构造 update 对象
  const update = { lane, action, hasEagerState: false, eagerState: null, next: null };

  // ③ 推到 hook 的循环队列尾
  enqueueUpdate(fiber, queue, update);

  // ④ 急切计算（小优化）：如果新 state === 旧 state，连 schedule 都省了
  if (fiber.lanes === NoLanes) {
    const eagerState = queue.lastRenderedReducer(currentState, action);
    update.eagerState = eagerState;
    update.hasEagerState = true;
    if (objectIs(eagerState, currentState)) return;  // ← bail out
  }

  // ⑤ 通知 scheduler 安排一次 render
  scheduleUpdateOnFiber(fiber, lane, eventTime);
}

三个 dispatcher — Hook 的真身在全局变量上

Three dispatchers — the real useState lives on a global

你写的 useState(0) 其实是个门面。它的实现只有一行:

The useState(0) you write is just a facade. Its implementation is a single line:

// packages/react/src/ReactHooks.js
export function useState<S>(initialState) {
  const dispatcher = resolveDispatcher();        // ← reads ReactCurrentDispatcher.current
  return dispatcher.useState(initialState);     // ← jumps to whichever dispatcher is "on"
}

"哪个 dispatcher 是 on 的"由 React 在不同的时机切换全局指针 ReactCurrentDispatcher.current 决定——共有三个完全独立的实现挂在那里。读完下面这张图,你下次再看到 "Hooks can only be called inside the body of a function component" 报错时,会知道是哪个指针在哪一瞬间指错了:

"Which dispatcher is on" is determined by React switching the global pointer ReactCurrentDispatcher.current at specific moments. Three independent implementations sit behind that pointer. After reading the figure below, the next time you see "Hooks can only be called inside the body of a function component", you'll know exactly which pointer was wrong, at which instant.

Hooks 巡礼 — 另外六个

Hooks tour — the other six

useContext · useMemo · useCallback · useRef · useSyncExternalStore · useTransition · useId

useContext · useMemo · useCallback · useRef · useSyncExternalStore · useTransition · useId

Counter 只用了 useState 和 useEffect——前一章把这两个的内核拆透。但 React 19 一共暴露 10+ 个 hook，理解它们的共同底层（同一条链表、同一个 dispatcher 切换机制）之后，每一个其实只是在 Hook 节点上挂不同形状的 memoizedState。这一章走 6 个最常见的剩余 hook。

Counter only uses useState and useEffect — the previous chapter cracked their kernel. But React 19 ships 10+ hooks. Once you grasp the shared substrate (single linked list, dispatcher swap), every hook is just a different shape of memoizedState on the Hook node. This chapter tours the six most-used remaining ones.

六个 Hook 在链表上的形态对照

The six hooks compared

useContext · 沿 fiber 树的依赖传播

useContext · dependency propagation through the fiber tree

useContext 是上面表里唯一不存值的 hook——它的 Hook 节点只挂一条依赖记录。值实际上活在 Provider 上方的上下文栈里，consumer 在 render 时读取的是栈顶。

useContext is the only hook in the table that stores no value — its Hook node only carries a dependency record. The actual value lives in the context stack above the Provider; consumer reads the top of stack during render.

// 简化版 readContext —— useContext 的实现核心
function readContext(context) {
  const value = context._currentValue;
  const dep = { context, memoizedValue: value, next: null };
  if (currentlyRenderingFiber.contextDependencies === null) {
    currentlyRenderingFiber.contextDependencies = { firstContext: dep };
  } else {
    lastContextDependency.next = dep;
  }
  lastContextDependency = dep;
  return value;
}

// 当 Provider 的 value 变化, React 调:
function propagateContextChange(wip, context, renderLanes) {
  let fiber = wip.child;
  while (fiber !== null) {
    let dep = fiber.contextDependencies?.firstContext;
    while (dep !== null) {
      if (dep.context === context) {
        fiber.lanes = mergeLanes(fiber.lanes, renderLanes); // 标记 dirty
        break;
      }
      dep = dep.next;
    }
    fiber = fiber.child ?? fiber.sibling ?? fiber.return; // 继续 DFS
  }
}

useMemo / useCallback · 缓存槽的真面目

useMemo / useCallback · the cache slot, unmasked

useMemo 和 useCallback 是同一段代码——后者只是前者的语法糖（useCallback(fn, deps) 等价于 useMemo(() => fn, deps)）。它们的"缓存"就是 Hook.memoizedState 里的一对 [deps, value]。

useMemo and useCallback share one implementation — the latter is sugar for the former (useCallback(fn, deps) ≡ useMemo(() => fn, deps)). Their "cache" is just a [deps, value] pair inside Hook.memoizedState.

function updateMemo(nextCreate, deps) {
  const hook = updateWorkInProgressHook();
  const prev = hook.memoizedState;
  if (prev !== null && areHookInputsEqual(deps, prev[1])) {
    return prev[0];                // ★ 命中: 返回旧值, 不调 nextCreate
  }
  const nextValue = nextCreate();
  hook.memoizedState = [nextValue, deps];
  return nextValue;
}

// areHookInputsEqual 用 Object.is 逐项比较 deps —— 浅比较, 不递归

useRef · 最简单的 Hook

useRef · the simplest hook

// 全部实现就这两行
function mountRef(initial) {
  const hook = mountWorkInProgressHook();
  const ref = { current: initial };
  hook.memoizedState = ref;
  return ref;
}
function updateRef(initial) {
  return updateWorkInProgressHook().memoizedState;  // 返回上次那个相同对象
}

就是一个 { current } 对象，跨 render 引用稳定。你改 ref.current 时 React 完全不知道——它不订阅、不调度、不重 render。这是 hook 里唯一合法允许 render 期间副作用的（但官方仍建议放在 useEffect 里）。

It's a { current } box, stable across renders. When you mutate ref.current, React doesn't know — no subscription, no schedule, no re-render. The only hook where render-time mutation is technically legal (though the docs still say move it to useEffect).

useSyncExternalStore · concurrent-safe 外部状态

useSyncExternalStore · concurrent-safe external state

React 18 之前订阅外部 store（Redux、Zustand）的标准做法是 useEffect + setState。Concurrent 来了之后这个 pattern 有个致命问题：同一次 render 中，不同组件可能在不同时间点读到 store——结果界面"撕裂"（tearing）。

Before React 18, subscribing to external stores (Redux, Zustand) used useEffect + setState. Concurrent mode broke this: within one render, different components might read the store at different points in time — the UI "tears".

// useSyncExternalStore 的核心: 一次 render 内 snapshot 一次, 然后保持
function useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) {
  const snapshot = getSnapshot();
  // 1. render 期间读取一次, 整个 render phase 都用这个值
  const hook = updateWorkInProgressHook();
  hook.memoizedState = [snapshot, getSnapshot];

  // 2. commit 之后 useEffect 注册 subscribe
  //    store 变化 → forceUpdate, 引发新 render, 新 render 再 snapshot
  useEffect(() => subscribe(() => {
    if (!Object.is(getSnapshot(), snapshot)) forceStoreRerender(fiber);
  }), [subscribe]);

  return snapshot;
}

// 这条 hook 是 Redux v8+/Zustand/Jotai 等所有现代外部状态库的底层 hook

useTransition / useDeferredValue · 把 setState 降级

useTransition / useDeferredValue · demoting a setState

两个 hook 都做同一件事：把某次 setState 从默认的 SyncLane / DefaultLane 降到 TransitionLane（参见 Ch16）。区别在 API 形状：

Both do the same thing: demote a setState from the default Sync/Default lane to TransitionLane (Ch16). Difference is purely API shape:

useId · SSR-safe 的确定性 ID

useId · SSR-safe deterministic IDs

React 17 之前，给 <label htmlFor> 生成稳定 id 非常痛苦——SSR 和客户端各自生成会不匹配（hydration mismatch）。useId 通过读取 fiber 树位置来生成 id：第 N 个深度 + 第 M 个位置 → 固定的字符串。服务器和客户端在同一棵树上必然产生相同 id。

Before React 17, stable ids for <label htmlFor> were painful — server and client each generated their own, mismatching during hydration. useId derives the id from the fiber tree position: depth N + position M → a fixed string. Server and client running the same tree get the same id.

// 生成出来的 id 形如 ":r0:", ":r1:", ":r2a:" ...
// 前缀 ":r" 是 HostRoot.identifierPrefix, 数字 + 字母是 fiber 在树上的路径

function Modal() {
  const id = useId();
  return <>
    <label htmlFor={`${id}-name`}>Name</label>
    <input id={`${id}-name`} />
    <label htmlFor={`${id}-email`}>Email</label>
    <input id={`${id}-email`} />
  </>;
}
// 一个 useId 调用 → 一个 id，但能拼出多个 DOM id（推荐用法）

useReducer · useState 的"大哥"

useReducer · the "elder sibling" of useState

很多人不知道：useState 的实现里真就是 useReducer，只是带了个固定的 reducer——basicStateReducer。

A truth few know: useState is literally a useReducer internally — with a fixed reducer called basicStateReducer.

// ReactFiberHooks.js · useState 的真实实现
function mountState(initial) {
  const hook = mountWorkInProgressHook();
  hook.memoizedState = hook.baseState =
    typeof initial === 'function' ? initial() : initial;

  const queue = {
    pending: null,
    lanes: NoLanes,
    dispatch: null,
    lastRenderedReducer: basicStateReducer,  // ← 写死了一个 reducer
    lastRenderedState: initial,
  };
  hook.queue = queue;
  const dispatch = dispatchSetState.bind(null, fiber, queue);
  return [hook.memoizedState, dispatch];
}

function basicStateReducer(state, action) {
  return typeof action === 'function' ? action(state) : action;
  // ★ 这就是 setState(n) 直接覆盖 vs setState(s => s+1) 函数式更新的分支
}

所以 useReducer 比 useState 更"原始"。何时选哪个？规则简单：状态更新逻辑超过一行就用 useReducer。理由：把"怎么变"集中到一个纯函数里，便于测试、便于复用、便于把 dispatch 透传给深层组件。

So useReducer is more "primitive" than useState. When to use which? Rule of thumb: if update logic is more than one line, prefer useReducer. Concentrates "how state changes" in a pure function — easier to test, reuse, and pass dispatch deep into the tree.

useImperativeHandle · 改 ref 暴露什么

useImperativeHandle · customizing what ref exposes

forwardRef 让 ref 穿过组件层级到达内部 DOM。useImperativeHandle 是 ref 的"过滤器"——它让你自定义父组件通过 ref 能拿到什么，而不是直接暴露内部 DOM。

forwardRef lets a ref pierce through component layers to inner DOM. useImperativeHandle is the filter: customize what the parent actually gets through ref, instead of exposing inner DOM raw.

const CustomInput = forwardRef(function CustomInput(props, ref) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    // 父组件只能调这 2 个方法，看不到原 input DOM
    focus: () => inputRef.current.focus(),
    clear: () => { inputRef.current.value = ''; },
    // 不暴露 .value, .style, 等等 → 父无法直接搞乱内部
  }), []);

  return <input ref={inputRef} {...props} />;
});

// 父用法:
const ref = useRef(null);
<CustomInput ref={ref} />
ref.current.focus();   // ✓ 可以
ref.current.value = 'x'; // ✗ undefined

在 commit 阶段的精确时机：useImperativeHandle 跟 useLayoutEffect 同步跑——在 Mutation 之后、Paint 之前。这意味着父组件 ref callback 收到的 ref.current 是最新版本，但只在下一个 commit。

Precise commit timing: useImperativeHandle runs synchronously alongside useLayoutEffect — after Mutation, before Paint. The parent's ref callback receives the fresh ref.current, but only on the next commit.

useInsertionEffect · 给 CSS-in-JS 库的特别窗口

useInsertionEffect · the CSS-in-JS exclusive window

React 18 引入的最少为人知的 hook。它在 useLayoutEffect 之前、Mutation 之前跑——专门给 styled-components / emotion 这种动态注入 CSS的库用的。为什么需要？因为 useLayoutEffect 时 DOM 已经存在，如果在那里注入 CSS，子组件 layout effect 读 DOM 几何会读到没应用样式的版本——尺寸全错。

The least-known hook React 18 introduced. It runs before useLayoutEffect, before Mutation — exclusively for libraries like styled-components / emotion that inject CSS dynamically. Why needed? By useLayoutEffect, DOM already exists; if you inject CSS there, child layout effects reading DOM geometry see unstyled dimensions — all wrong.

// CSS-in-JS 库内部大致这么用
function useStyleInjection(css) {
  useInsertionEffect(() => {
    const style = document.createElement('style');
    style.textContent = css;
    document.head.appendChild(style);
    return () => style.remove();
  }, [css]);
}

// 这个 hook 你 99% 用不到 —— 它存在的全部目的是给三方库用
// 应用代码里出现 useInsertionEffect 几乎肯定是错用了

React 19 表单三件套 · Actions 时代

React 19 form trio · the Actions era

React 19 把"提交表单" 升级成了 first-class abstraction。三个 hook 配合一起干掉了一大半 redux 样板：

React 19 promotes "form submission" to a first-class abstraction. Three hooks together replace half the redux boilerplate:

// 一个完整的"乐观 + 服务器 action + pending 状态"组合
async function addTodo(prevState, formData) {
  'use server';
  return { todos: [...prevState.todos, await db.insert(formData.get('text'))] };
}

function TodoForm({ initialTodos }) {
  // ① 把 action 接到 React state 管理
  const [state, action, isPending] = useActionState(addTodo, { todos: initialTodos });

  // ② 乐观更新 · 让 UI 立刻反映新 todo
  const [optimistic, addOpt] = useOptimistic(state.todos,
    (curr, newTodo) => [...curr, { text: newTodo, pending: true }]
  );

  return <form action={(fd) => {
    addOpt(fd.get('text'));  // 立即乐观
    action(fd);                // 真请求
  }}>
    {optimistic.map(t => <Item data={t} />)}
    <input name="text" />
    <SubmitBtn />          // SubmitBtn 内部用 useFormStatus 读 pending
  </form>;
}

function SubmitBtn() {
  const { pending } = useFormStatus();   // 读最近的 form action 状态
  return <button disabled={pending}>{pending ? '…' : 'Add'}</button>;
}

useDebugValue · 给 DevTools 看

useDebugValue · for DevTools eyes only

最简单的 hook，唯一作用是在 React DevTools 的 Components 面板里给自定义 hook 显示一个"友好标签"。生产环境完全 noop。

The simplest hook. Its sole job: show a "friendly label" for custom hooks in React DevTools' Components panel. Completely noop in production.

function useUser(id) {
  const [user, setUser] = useState(null);
  useDebugValue(user ? `User: ${user.name}` : 'loading');
  // DevTools Components 里会显示: useUser · "User: Alice"
  // 不写 useDebugValue 就只显示: useUser
  ...
  return user;
}

Before Mutation — commit 的第一刀

Before Mutation — first cut of commit

读 DOM · getSnapshotBeforeUpdate · 但还不能写

read DOM · getSnapshotBeforeUpdate · no writes yet

Commit Phase 在浏览器一个微任务内一气呵成跑完——它不可中断，因为一旦 DOM 被改了一半，UI 就会显示不一致状态。React 把 commit 拆成 3 个子阶段，每个子阶段都明确"允许做什么 / 禁止做什么"：

Commit runs inside a single browser microtask — uninterruptible, because a half-mutated DOM would flash inconsistent UI. React splits commit into 3 sub-phases, each with explicit "allowed / forbidden" semantics:

"Before Mutation" 这个名字非常准确——它的特权是：DOM 还没改，所以你能拿到"修改前的真实状态"。componentDidUpdate 之前的 getSnapshotBeforeUpdate 就跑在这里——它的经典用例是滚动位置保持：

"Before Mutation" is precise — its privilege is: DOM is still old, so you can read "state before the change". getSnapshotBeforeUpdate runs here. Classic use case: preserve scroll position when prepending items:

class ChatLog extends Component {
  // 在 DOM 改之前测一下：底部还有多少滚动空间
  getSnapshotBeforeUpdate(prevProps) {
    if (prevProps.messages.length < this.props.messages.length) {
      const list = this.listRef.current;
      return list.scrollHeight - list.scrollTop;  // snapshot
    }
    return null;
  }

  // 在 DOM 改完之后用 snapshot 恢复滚动
  componentDidUpdate(prevProps, prevState, snapshot) {
    if (snapshot !== null) {
      const list = this.listRef.current;
      list.scrollTop = list.scrollHeight - snapshot;
    }
  }
}

三个真实用例 · 为什么这个子阶段不能没

Three real use cases · why this sub-phase exists at all

BeforeMutation 看起来"什么都不做"——但它是唯一 同时满足两个条件的窗口：① 新 React 树已经决定好（render phase 已完成），② DOM 还没改。下面三个工业级用例只能在这里实现：

BeforeMutation looks like it "does nothing" — but it's the only window meeting two conditions: ① the new React tree is decided (render phase done), ② DOM is unchanged yet. Three production use cases that can only happen here:

getSnapshotBeforeUpdate 完整实战

getSnapshotBeforeUpdate · full case

class ChatLog extends Component {
  listRef = createRef();

  // BeforeMutation 子阶段调用 · DOM 还是旧的
  getSnapshotBeforeUpdate(prevProps, prevState) {
    // 检测是否在追加消息
    if (prevProps.messages.length < this.props.messages.length) {
      const list = this.listRef.current;
      // 记下"剩余可滚动距离" —— 这个值是 layout-invariant 的
      return { scrollFromBottom: list.scrollHeight - list.scrollTop };
    }
    return null;
  }

  // Layout 子阶段调用 · DOM 已改, snapshot 是上面那个返回值
  componentDidUpdate(prevProps, prevState, snapshot) {
    if (snapshot !== null) {
      const list = this.listRef.current;
      // 用 snapshot 算出新 scrollTop, 保持视口稳定
      list.scrollTop = list.scrollHeight - snapshot.scrollFromBottom;
    }
  }

  render() {
    return <div ref={this.listRef} className="log">
      {this.props.messages.map(m => <Msg key={m.id} {...m} />)}
    </div>;
  }
}

为什么 hooks 没有对应 API

Why hooks have no equivalent

很多人问: 为什么 React 19 都不出 useSnapshotBeforeUpdate? 答案在生命周期: getSnapshotBeforeUpdate 接收 prevProps, prevState 然后返回值传给 componentDidUpdate——它是跨子阶段通信的一种同步缝合。Hook 模型里没有"上一次 render 的 props/state" 这个概念 (hook 是单次 render 内的, 没有 prev/curr 视图)。React 团队的官方建议: 用 ref 自己存 prev——但精确的commit 子阶段时机仍只能靠 class 拿到。这是 hook 模型一个真正的 边界。

A frequent question: why doesn't React 19 ship a useSnapshotBeforeUpdate? Answer is in the lifecycle: getSnapshotBeforeUpdate receives prevProps, prevState and pipes a return value into componentDidUpdate — a sync stitch across sub-phases. The hooks model has no "previous render's props/state" concept (hooks are per-render, no prev/curr view). React's official advice: store prev in a ref yourself — but the precise commit-sub-phase timing remains class-only. This is a real boundary of the hooks model.

Mutation — DOM 真的动了

Mutation — DOM actually changes

commitPlacement · commitUpdate · commitDeletion

commitPlacement · commitUpdate · commitDeletion

这是 React 整个流水线里唯一真的改 DOM 的阶段。它按 fiber.flags 分发处理：

The only phase that touches the DOM. Dispatches on fiber.flags:

root.current 切换 — 一切的转折点

root.current swap — the turning point

Mutation 子阶段跑完之后、Layout 子阶段开始之前，React 做了一件极其关键的事：root.current = finishedWork。这一行让"workInProgress 树变成 current 树"，双缓冲翻转。这是 React 内部"新版本上线"的瞬间——之前任何 ref 读到的都是旧版，之后任何 ref 读到的都是新版。

Between Mutation and Layout, React does the critical line: root.current = finishedWork. This flips the double buffer — "workInProgress becomes current". The instant where the new version goes live: any ref read before this points at the old tree; any ref after points at the new.

// react-reconciler/src/ReactFiberWorkLoop.js · the pivot
function commitRootImpl(root, recoverableErrors, transitions) {
  // PHASE 1 — Before Mutation
  commitBeforeMutationEffects(root, finishedWork);

  // PHASE 2 — Mutation
  commitMutationEffects(root, finishedWork, lanes);
  resetAfterCommit(root.containerInfo);

  // ★★★ THE SWAP ★★★
  root.current = finishedWork;

  // PHASE 3 — Layout (sync)
  commitLayoutEffects(finishedWork, root, lanes);

  // Schedule Passive Effects (async, 下一节)
  scheduleCallback(NormalPriority, flushPassiveEffects);
}

Portal · 跨 container 的 commit

Portal · cross-container commit

createPortal(children, otherContainer) 让一棵子树渲染到另一个 DOM container——典型场景是 Modal / Tooltip / Dropdown，它们需要逃出父级的 overflow: hidden 或 z-index 栈。但 portal 是commit 阶段才生效的——render phase 里 portal fiber 看起来跟普通组件没区别。

createPortal(children, otherContainer) renders a subtree into a different DOM container — typical for Modals / Tooltips / Dropdowns that need to escape a parent's overflow: hidden or z-index stack. But portals are a commit-phase phenomenon — during render phase a portal fiber looks like any other component.

function Modal({ children }) {
  return ReactDOM.createPortal(
    <div className="modal-content">{children}</div>,
    document.getElementById('modal-root')   // ← 另一个 DOM container
  );
}
// JSX 上看 Modal 在 App 里; 但 DOM 上 modal-content 挂到 #modal-root 下

Mutation 子阶段的精确执行顺序

Mutation sub-phase · exact execution order

Mutation 不是一个"原子操作"——它内部有严格的子步顺序。这个顺序决定了 ref 时机、cleanup 时机、portal commit 时机的所有正确性。读 React 源码时如果你看到反直觉的 bug, 99% 跟下面这张顺序表对不上有关：

Mutation isn't an "atomic operation" — internally it has a strict sub-step order. This order dictates correctness for ref timing, cleanup timing, portal commit timing. When you see counterintuitive bugs in React source, 99% is a mismatch with this table:

ChildDeletion 内部子顺序

ChildDeletion · its internal order

删除一棵子树不是一个 removeChild 那么简单——React 要确保子孙的清理按照"反向 mount 顺序"跑完。一个 deletion 在 fiber 内部走这条精确路径:

Deleting a subtree is not a single removeChild — React must ensure descendants' cleanup runs in reverse mount order. A deletion follows this exact internal path:

// commitDeletionEffectsOnFiber · 深度优先 post-order
function commitDeletionEffectsOnFiber(root, returnFiber, deletedFiber) {
  // ① 先递归到最深处, 子孙先卸
  let child = deletedFiber.child;
  while (child !== null) {
    commitDeletionEffectsOnFiber(root, returnFiber, child);
    child = child.sibling;
  }

  switch (deletedFiber.tag) {
    case HostComponent:
      // ② detach ref · 安全无副作用
      safelyDetachRef(deletedFiber, returnFiber);
      break;

    case FunctionComponent:
      // ③ 运行所有 useEffect cleanup · ④ 所有 useLayoutEffect cleanup
      commitHookEffectListUnmount(HookPassive, deletedFiber, returnFiber);
      commitHookEffectListUnmount(HookLayout, deletedFiber, returnFiber);
      break;

    case ClassComponent:
      // ⑤ 调 componentWillUnmount
      safelyCallComponentWillUnmount(deletedFiber, returnFiber);
      break;
  }
}

// 整棵子树 cleanup 跑完之后, returnFiber 才调一次 removeChild
// 把整个 子树的根 DOM 节点从父 DOM 摘掉
returnFiber.stateNode.removeChild(deletedFiber.stateNode);

Portal 内部的 mutation 顺序

Mutation order inside a Portal

Portal 增加了一个反直觉点: 它的容器跟父 fiber 的容器不同。commitMutationEffectsOnFiber 处理到一个 HostPortal fiber 时, 会临时切换 container 引用到 portal 自带的 container, 然后递归处理子树。完成后切回原 container。所以一次 commit 里如果有多个 portal, container 引用会被"压栈"——React 用一个隐式 stack 管理这件事。

Portal adds a counterintuitive twist: its container differs from the parent fiber's container. When commitMutationEffectsOnFiber processes a HostPortal fiber, it temporarily swaps the container reference to the portal's own container, recurses into the subtree, then swaps back. So a commit with multiple portals "stacks" container references — React manages this with an implicit stack.

// commitMutationEffects 简化
function commitMutationEffectsOnFiber(finishedWork, root) {
  switch (finishedWork.tag) {
    case HostPortal: {
      const oldContainer = currentMutationContainer;
      currentMutationContainer = finishedWork.stateNode.containerInfo;
      // ↑ 切到 portal 的 container (#modal-root)

      recursivelyTraverseMutationEffects(root, finishedWork);
      commitReconciliationEffects(finishedWork);

      currentMutationContainer = oldContainer;  // 切回原 container
      break;
    }
    // ... 其他 tag ...
  }
}

为什么 commit 不能切片

Why commit can't be sliced

读完上面顺序表后, "commit 必须同步一气呵成" 这件事就显然了——任何中断都会让 DOM 处于半改不改 的状态 (有些子树已用新 DOM, 有些还用旧的)。用户看到的可能是: 5 个 todo 里前 3 个标了"done"样式, 后 2 个还是"open"——这就是视觉撕裂。React 18 Concurrent 让 render 可切片是因为 render 的中间状态只在内存里; 但 commit 的中间状态是用户屏幕上的——这是 React 18 RFC 里反复强调的不可突破的边界。

After reading the order table, "commit must be synchronous, all-or-nothing" becomes obvious — any interruption leaves DOM in a half-mutated state (some subtrees on new DOM, others on old). User might see: of 5 todos, first 3 styled "done", last 2 still "open" — visual tear. React 18 Concurrent slices render because render's intermediate state is memory-only; commit's intermediate state is on the user's screen. The React 18 RFC repeatedly stresses this as an unbreakable boundary.

Layout & Passive — useLayoutEffect vs useEffect

Layout & Passive — useLayoutEffect vs useEffect

同步 vs 异步 · paint 前 vs paint 后

sync vs async · before paint vs after paint

Cleanup 的两次时机

Cleanup runs twice

每个 effect 的 cleanup 函数在两个位置被调用：①下次 effect 触发之前（确保旧订阅被解绑），②组件卸载时。React 18 StrictMode 在开发模式下故意 mount → cleanup → mount 两遍，专门曝光那些"没好好写 cleanup"的 effect。React 19 把这个习惯保留了——它是发现 effect bug 最有效的工具。

An effect's cleanup fires at two moments: ① before the next effect (so old subscriptions detach), ② on unmount. React 18 StrictMode dev-only mounts → cleans → mounts again on purpose, to expose effects without proper cleanup. React 19 kept this — most effective tool we have for catching effect bugs.

Error Boundaries — 异常的另一条上溯路径

Error Boundaries — the other exception path

getDerivedStateFromError · componentDidCatch · React 19 三回调

getDerivedStateFromError · componentDidCatch · React 19's three callbacks

Suspense 用 throw Promise 做控制流（Ch18）。Error Boundary 用同一套机制——只是 throw 的是 真 Error。两条路径在 ReactFiberThrow.js 的同一个函数 throwException 里分发：是不是 thenable？是 → 走 Suspense 路径；不是 → 走 ErrorBoundary 路径。这是 React 17 之后两套"抛出即控制流"机制在源码里的对称美。

Suspense uses thrown Promises as control flow (Ch18). Error Boundaries use the same mechanism — except they throw a real Error. Both paths dispatch from one function in ReactFiberThrow.js: throwException. Is it a thenable? → Suspense path. Otherwise → ErrorBoundary path. This is the source-code symmetry of two "throw-is-control-flow" mechanisms post-React-17.

为什么必须是 class 组件

Why it must be a class component

2026 年了 hook 几乎无所不能——但 Error Boundary 至今没有 hook 版。原因不是 React 团队懒，是语义问题：

It's 2026 and hooks do almost everything — except Error Boundaries, which still have no hook version. Not laziness — a semantic problem:

两个生命周期的精确时机

Precise timing of the two lifecycles

class ErrorBoundary extends Component {
  state = { hasError: false, error: null };

  // ★ 在 RENDER PHASE 里被调用 (必须纯, 不能 side-effect)
  static getDerivedStateFromError(error) {
    return { hasError: true, error };  // 仅返回新 state
  }

  // ★ 在 COMMIT PHASE 里被调用 (可 side-effect: log / 上报)
  componentDidCatch(error, errorInfo) {
    sentry.captureException(error, errorInfo);
    // errorInfo.componentStack: "    in Avatar\n    in UserCard\n..."
  }

  render() {
    if (this.state.hasError) return <FallbackUI />;
    return this.props.children;
  }
}

React 19 的三个 root 级回调

React 19's three root-level callbacks

React 19 把"错误监控"从分散在各个 ErrorBoundary 提到了整个 root。createRoot 现在接 3 个回调：

React 19 lifts "error observation" from scattered ErrorBoundaries to the entire root. createRoot now takes 3 callbacks:

const root = createRoot(container, {
  // 没被任何 boundary 接住 · 用户 UI 会白屏
  onUncaughtError(error, errorInfo) {
    sentry.captureException(error, { ...errorInfo, severity: 'critical' });
  },

  // 被某个 boundary 接住了 · 用户看到 fallback
  onCaughtError(error, errorInfo) {
    sentry.captureException(error, { ...errorInfo, severity: 'warning' });
  },

  // 可恢复的: React 自动重试成功了 · 比如 hydration mismatch 自愈
  onRecoverableError(error, errorInfo) {
    analytics.log('recovered', error.message);
  },
});

边界粒度 · 全局 boundary 是个反模式

Boundary granularity · a global boundary is an antipattern

初学者常犯的错：把整个 App 包在一个 ErrorBoundary 里。这意味着任何一个子组件出错都让整个页面 fallback。正确做法是边界细粒度化——通常一个有意义的独立功能区就是一个 boundary：

Beginner mistake: wrap the whole App in one ErrorBoundary. Now any error blows the entire page to fallback. Correct: granular boundaries — typically one per meaningful independent feature area:

// 反模式 · 一个挂全挂
<ErrorBoundary>
  <App />
</ErrorBoundary>

// 正确 · 每个独立 feature 一个
<ErrorBoundary fallback={'header 出错'}>
  <Header />
</ErrorBoundary>
<ErrorBoundary fallback={'文章加载失败'}>
  <ArticleContent />
</ErrorBoundary>
<ErrorBoundary fallback={'评论暂不可用'}>
  <CommentList />
</ErrorBoundary>
// 一个 feature 挂掉, 其他依然正常

Automatic Batching — React 18 最沉默的革命

Automatic Batching — React 18's quietest revolution

从 event-boundary 到 lane-based · 跨 setTimeout/Promise 自动合并

from event-boundary to lane-based · cross-setTimeout/Promise auto-batching

"Automatic Batching" 是 React 18 最不起眼的特性——发布博客只用一段话讲, RFC 没几个人读, 但它悄悄改了一件根本性的事: setState 多次调用什么时候被合并成一次 render。这个边界在 React 17 是按事件类型定的, 18 改成了按 lane 定。这个一字之差让跨 setTimeout / Promise / fetch / 第三方库回调的 setState 也能自动合并——大量手写优化代码瞬间过时。

"Automatic Batching" is React 18's least-noticed feature — the release post mentions it briefly, the RFC barely read, but it quietly changed something fundamental: when multiple setState calls coalesce into one render. In React 17 this boundary was decided by event type; in 18 it's decided by lane. That one-word swap made setStates across setTimeout / Promise / fetch / third-party callbacks also batchable — overnight obsoleting reams of hand-written optimization.

React 17 之前 · event-boundary batching

Pre-React 17 · event-boundary batching

// React 17 的 batching 边界 (简化)
function batchedEventUpdates(fn, e) {
  const prevBatching = isBatching;
  isBatching = true;                       // 开启 batch
  try {
    return fn(e);                          // 跑用户 handler
  } finally {
    isBatching = prevBatching;                // 关闭 batch
    if (!isBatching) flushSyncCallbackQueue();// 一次性 flush
  }
}

// React 17: 这个 handler 触发 1 次 render
handleClick = () => {
  setCount(c + 1);
  setName("Alice");  // 两个 setState 在同一 batch
};

// React 17: 这个 handler 触发 2 次 render (灾难)
handleClick = () => {
  fetch('/api').then(() => {
    setCount(c + 1);      // fetch.then 已经出了原 handler 范围
    setName("Alice");     // isBatching === false → 每个 setState 独立 render
  });
};

React 18 之后 · lane-based batching

React 18+ · lane-based batching

React 18 把"是不是在 batch" 这个全局开关彻底去掉了。新逻辑: setState 永远把更新推入 lane 队列, scheduler 在下一个微任务 (microtask) 决定是否 flush。多个 setState 落在同一 lane (或纠缠 lane) 自然合并——跟在不在 event handler 里无关。

React 18 fully removes the "are we batching" global flag. New logic: setState always enqueues into a lane queue; scheduler decides when to flush at the next microtask. Multiple setStates landing in the same lane (or entangled lanes) naturally coalesce — unrelated to whether you're in an event handler.

// React 18+ 的 batching 核心 (简化)
function scheduleUpdateOnFiber(fiber, lane) {
  fiber.lanes |= lane;
  let root = fiber;
  while (root.return) {
    root.return.childLanes |= lane;
    root = root.return;
  }
  root.pendingLanes |= lane;

  // ★ 不立即 render! 排个微任务
  ensureRootIsScheduled(root);
}

function ensureRootIsScheduled(root) {
  if (root.callbackNode !== null) return; // 已经排过, 不重复

  const nextLane = getNextLane(root.pendingLanes);

  if (nextLane === SyncLane) {
    // SyncLane 用 microtask flush — 比 setTimeout(0) 快
    queueMicrotask(() => performSyncWorkOnRoot(root));
  } else {
    // Concurrent lanes 用 scheduler 的 MessageChannel
    root.callbackNode = Scheduler.scheduleCallback(...);
  }
}

// React 18: 现在两种写法都是 1 次 render
handleClick = () => {
  fetch('/api').then(() => {
    setCount(c + 1);
    setName("Alice");
    // 两个 setState 推入同一 lane, 同一 microtask flush → 1 次 render ✓
  });
};

flushSync · 强制冲刷 escape hatch

flushSync · the force-flush escape hatch

99% 的情况你希望自动 batching, 但有极少情况你需要"这个 setState 立刻 render 完, 我下一行代码要读新 DOM"。React 18 提供 flushSync 作为 escape hatch:

99% of the time you want automatic batching, but in rare cases you need "render this setState immediately, the next line reads the new DOM". React 18 ships flushSync as the escape hatch:

import { flushSync } from 'react-dom';

function handleScroll() {
  flushSync(() => {
    setShowDetails(true);    // 立即同步 render + commit
  });
  // 这一行执行时, <Details /> 已经在 DOM 里了
  detailsRef.current.scrollIntoView();   // 滚到刚显示的元素
}

unstable_batchedUpdates · 历史的残骸

unstable_batchedUpdates · historical relic

React 17 之前, 如果你想要"在 setTimeout 里也 batch", 你得手写 ReactDOM.unstable_batchedUpdates(() => {...})。这个 API 从 React 0.13 就有, 一直 unstable 了 10 年——因为 React 团队知道它该被自动化掉。React 18 正式 ship Automatic Batching 后, 这个 API 变成no-op——它仍存在 (为了向后兼容), 但里面什么都不做。今天的代码库里如果还看到它, 是 React 16/17 时代的考古遗物, 可以放心删。

Pre-React 17, if you wanted "batch inside setTimeout too", you wrote ReactDOM.unstable_batchedUpdates(() => {...}). This API existed since React 0.13, unstable for 10 years — because the React team knew it should be automated away. After React 18 shipped Automatic Batching, this API became a no-op — it still exists (backwards compat) but does nothing inside. If you see it in modern code, it's archaeology from the React 16/17 era; safe to delete.

Counter ACT III 是 batching 的真正展示

Counter ACT III is the real batching demo

回到本文主线: Counter 的 ACT III 是"3 ms 内连点两次"。这两次 click 是两个独立 DOM event, 不是一个 handler 里的两次 setState。在 React 17 下, 它们必然产生 2 次 render。在 React 18 下, 如果两次 click 都被排到同一个 microtask 之前——它们会合并成 1 次 render。这是 lane-based batching 的隐性收益: 用户高频操作不再产生帧抖动。

Back to the through-line: Counter's ACT III is "two clicks within 3 ms". These are two separate DOM events, not two setStates in one handler. In React 17 they always produce 2 renders. In React 18, if both clicks arrive before the same microtask flush — they coalesce into 1 render. The implicit benefit of lane-based batching: high-frequency user input no longer causes frame jitter.

Lanes — 31 条优先级车道

Lanes — 31 priority channels

用位掩码替代优先级队列

a bitmask instead of a priority queue

React 16 用过期时间（expirationTime，单位 ms）表示更新优先级——精确但实现复杂，尤其在合并多个 update 时。18 改成了 Lanes：一个 31 位的位掩码，每位代表一种优先级。低位优先级高，高位优先级低。一棵子树的"待办任务" = 它和所有子孙的 lanes 按位或。

React 16 used expirationTime (ms) to encode priority — precise but complex when merging updates. 18 replaced it with Lanes: a 31-bit bitmask, one bit per priority class. Lower bits = higher priority. A subtree's "work to do" = OR of its and all descendants' lanes.

31 条车道地图

All 31 lanes

// ReactFiberLane.js · simplified
export const NoLanes                = 0b0000000000000000000000000000000;
export const SyncLane               = 0b0000000000000000000000000000010; // click / 用户输入
export const InputContinuousLane    = 0b0000000000000000000000000001000; // mousemove / scroll
export const DefaultLane            = 0b0000000000000000000000000100000; // 普通 setState
export const TransitionLanes        = 0b0000000001111111111111111000000; // 16 条 transition 车道
export const RetryLanes             = 0b0000111100000000000000000000000; //  4 条 Suspense 重试
export const IdleLane               = 0b0100000000000000000000000000000; // 最低，可被任何事打断
export const OffscreenLane          = 0b1000000000000000000000000000000; // <Activity> 隐藏树

为什么是位运算

Why bitwise

Lanes 设计的核心追求是合并和查询都要快。位运算让这两件事都是 1 个 CPU 周期：

Lanes target one thing: merge + query in one CPU cycle. Bitwise wins:

Time Slicing — 5ms 一个切片

Time Slicing — 5 ms a slice

MessageChannel · shouldYield · 调度器内部

MessageChannel · shouldYield · inside the scheduler

scheduler 包是 React 团队从一开始就有分离野心的产物——它不依赖 React 任何东西，可以单独 npm 用。它只做一件事：让一段任务在不阻塞浏览器的前提下分批跑完。它的核心是两件事：用 MessageChannel 当让步机制，用 小顶堆 管理任务队列。

The scheduler package was always meant to be standalone — depends on no React internals, ships separately on npm. Its only job: run a task across batches without blocking the browser. Two pieces: MessageChannel as yield mechanism, min-heap as task queue.

为什么不用 requestIdleCallback

Why not requestIdleCallback

// scheduler/src/SchedulerPostTask.js · 简化版
const channel = new MessageChannel();
const port = channel.port2;
channel.port1.onmessage = performWorkUntilDeadline;

function requestHostCallback(callback) {
  scheduledHostCallback = callback;
  port.postMessage(null);    // 触发下一个 task
}

function performWorkUntilDeadline() {
  const startTime = getCurrentTime();
  deadline = startTime + frameInterval; // 5 ms
  try {
    const hasMore = scheduledHostCallback(deadline);
    if (hasMore) port.postMessage(null); // 再来一片
  } finally {
    needsPaint = false;
  }
}

function shouldYield() {  // React workLoop 每个 Fiber 后调一次
  return getCurrentTime() >= deadline;
}

为什么是 5ms

Why 5 ms

60 fps = 16.7 ms/帧。但浏览器自己（layout / paint / GC / 输入分发）也要时间。Andrew Clark 2019 年 PR 把切片预算定在 5 ms——大部分常见 Fiber 处理时间都在 1ms 内，5ms 能在让步前跑完一个组件树的一两层，又留足 11ms 给浏览器自己。Meta 用 200K LOC 的 React app 实测后选定的数。

60 fps = 16.7 ms/frame. The browser itself (layout / paint / GC / input dispatch) needs time too. Andrew Clark's 2019 PR fixed the slice budget at 5 ms — typical Fiber work is <1 ms each; 5 ms covers a couple of subtree levels before yielding, leaving 11 ms for the browser. Meta benchmarked this on a 200K-LOC React app and stuck with it.

Concurrent 的代价 — 没人公开讨论的部分

The cost of Concurrent — what nobody talks about

Concurrent Mode 的卖点都被讲烂了——可中断、可丢弃、不阻塞输入。但它的真实代价很少有人写。在 React 19 默认开启 Concurrent 三年之后，下面这四笔账值得认账：

The Concurrent sales pitch is overdone — interruptible, discardable, doesn't block input. The real costs, less so. Three years into React 19 shipping Concurrent on by default, four bills are due:

Entangled Lanes · 车道纠缠

Entangled Lanes · lane entanglement

Lane 模型有个反直觉的设计：两条 lane 可以"纠缠"。意思是 React 会把它们视为同一条——一条触发，另一条必须一起跑完。这个机制存在的全部理由：避免 tearing。

The lane model has a counterintuitive design: two lanes can be "entangled" — React treats them as one, so when one triggers, the other must run together. Reason for existing: prevent tearing.

最常见的纠缠场景是 useSyncExternalStore（Ch12B）。当一个外部 store 同时被同步代码和 transition 代码读时，它们不能用不同的 store 快照渲染——否则同一屏上一半组件显示旧值、一半显示新值。React 通过把这些 lane 纠缠到一起来强制一致性。

The classic case is useSyncExternalStore (Ch12B). When an external store is read by both sync code and transition code, they cannot render with different store snapshots — half the screen on old, half on new = tear. React entangles those lanes to enforce consistency.

// ReactFiberLane.js · entanglement 数据结构
type FiberRoot = {
  ...
  entangledLanes: Lanes,                // 总位掩码: 哪些 lane 处于纠缠中
  entanglements: LaneMap<Lanes>,     // 每条 lane 纠缠了哪些其他 lane
};

function markRootEntangled(root, entangledLanes) {
  root.entangledLanes |= entangledLanes;
  let lanes = entangledLanes;
  while (lanes) {
    const index = pickArbitraryLaneIndex(lanes);
    const lane = 1 << index;
    root.entanglements[index] |= entangledLanes;  // 双向纠缠
    lanes &= ~lane;
  }
}

Starvation Protection · 5 秒饥饿提升

Starvation Protection · 5-second priority elevation

优先级模型有个经典问题：低优先级永远等不到。想象一棵被 startTransition 包的列表渲染——它在 TransitionLane 上跑，正常情况会被切片完成。但如果用户每秒不停打字，每次 keystroke 都把 SyncLane 优先级抬上来，TransitionLane 永远没机会获得完整的时间片——它饿死了。

A classic priority-model bug: low-priority never gets its turn. Picture a list render wrapped in startTransition — running on TransitionLane, sliced normally. If the user types continuously, each keystroke pumps SyncLane priority up; TransitionLane never gets a clean slice — it starves.

React 用过期时间解决这个：每条 lane 都有一个隐式的 expirationTime。如果某条 lane 的等待时间超过阈值，React 在下次 schedule 时把它当作 SyncLane来跑——一定一次跑完，不再切片。

React's fix: expiration time. Every lane has an implicit expirationTime. If a lane has waited beyond its threshold, React schedules it as if it were SyncLane the next time — runs to completion, no slicing.

// ReactFiberLane.js · 各级 lane 的过期时间
function computeExpirationTime(lane, currentTime) {
  switch (lane) {
    case SyncLane:
    case InputContinuousLane:
      return NoTimestamp;       // 立即, 不需要过期机制
    case DefaultLane:
      return currentTime + 5000;  // 5 秒后强制完成
    case TransitionLane1:
    case TransitionLane2:
    ...
      return currentTime + 5000;  // 5 秒后强制完成
    case IdleLane:
      return NoTimestamp;       // 永不过期 (用 idle 本就是接受永等)
  }
}

function markStarvedLanesAsExpired(root, currentTime) {
  let lanes = root.pendingLanes;
  while (lanes) {
    const index = pickArbitraryLaneIndex(lanes);
    const lane = 1 << index;
    const expirationTime = root.expirationTimes[index];
    if (expirationTime !== NoTimestamp && expirationTime <= currentTime) {
      root.expiredLanes |= lane;   // ★ 标记为已过期, 下次按 SyncLane 跑
    }
    lanes &= ~lane;
  }
}

这个 5 秒不是随便定的：用户能忍受"稍微卡一下"的最大时长大约就是 5 秒——再长用户会以为应用挂了。React 用这个数字平衡两边：5 秒内尽量保持响应（切片可中断），超过就宁可卡 100ms 也要完成。

5 seconds isn't arbitrary: ~5 seconds is the longest a user tolerates "a bit of lag" before assuming the app is broken. React balances both sides: within 5 s, stay responsive (slice + interruptible); beyond, better to block 100 ms than starve forever.

Interruption Semantics — 中断之后, React 怎么恢复?

Interruption Semantics — how React resumes after a yield

workInProgressRoot · same-lane resume · higher-lane restart · prepareFreshStack

workInProgressRoot · same-lane resume · higher-lane restart · prepareFreshStack

前一章把"怎么让出"讲完了——shouldYield() 返回 true,workLoop 退出。但下一次回来的时候,React 到底是接着画,还是从头再来? 这个问题前面被一笔带过,实际上是 Concurrent Mode 最容易踩坑的部分,也是面试时"concurrent 鸡毛蒜皮"的高频提问点。这一章把三条出路全摊开。

Last chapter explained "how to yield" — shouldYield() returns true, workLoop bails out. But when React comes back, does it resume where it left off, or start fresh? Previously brushed over. This is the trickiest part of Concurrent Mode, and a top interview-question source. This chapter lays out all three exits.

三个状态变量 — React 怎么记住"我画到哪了"

Three state variables — how React remembers "where I was"

// packages/react-reconciler/src/ReactFiberWorkLoop.js — module-level state
let workInProgressRoot: FiberRoot | null = null;             // 正在 render 哪棵 root
let workInProgress: Fiber | null = null;                  // 下一步要 begin 哪个 fiber
let workInProgressRootRenderLanes: Lanes = NoLanes;          // 这次 render 持有的车道
let workInProgressRootExitStatus: RootExitStatus = NotStartedYet; // IN-PROGRESS / SUSPENDED / COMPLETED

让步那一刻 React不清空这些变量——它们就那么挂在 module scope 上。等到下次 scheduler 又有 5 ms 给你时,performConcurrentWorkOnRoot 进来,第一件事是检查这些变量:

On yield, React does not clear these variables — they hang on module scope. When the scheduler hands back 5 ms, performConcurrentWorkOnRoot enters and inspects them first thing:

prepareFreshStack — restart 那一刻发生什么

prepareFreshStack — what happens at a restart

// react-reconciler/src/ReactFiberWorkLoop.js · simplified
function prepareFreshStack(root: FiberRoot, lanes: Lanes): Fiber {
  root.finishedWork = null;
  root.finishedLanes = NoLanes;

  // 1. 把之前 wip 上的 Effects 也清掉(不然 commit 时会跑过期的 effect)
  const timeoutHandle = root.timeoutHandle;
  if (timeoutHandle !== noTimeout) {
    root.timeoutHandle = noTimeout;
    cancelTimeout(timeoutHandle);
  }

  // 2. workInProgress 重新指回 root → 整个 wip 树就 garbage 了
  //    (旧 wip fiber 还在内存里, 但通过 alternate 链已经访问不到, 等 GC)
  workInProgressRoot = root;
  const rootWorkInProgress = createWorkInProgress(root.current, null);
  workInProgress = rootWorkInProgress;
  workInProgressRootRenderLanes = subtreeRenderLanes = lanes;

  // 3. context stack / hooks dispatcher 也重置——任何"render 过程的副作用"全部回退
  resetContextDependencies();
  finishQueueingConcurrentUpdates();
  workInProgressRootExitStatus = RootInProgress;

  return rootWorkInProgress;
}

这就是为什么 "render 阶段必须是纯函数" 不是一句教学口号——而是 Concurrent 架构强制的物理约束。如果 render 中你打印了一个 console.log("hi"),那次 restart 之后这句话会被再打印一次——因为整个 render 重新跑。React 18 在 dev StrictMode 下故意 双重渲染 你的 component, 就是故意暴露这个语义: 不是 React bug, 是 Concurrent 架构的物理事实。

This is why "render must be a pure function" isn't pedagogy — it's a physical constraint of Concurrent. If render contains console.log("hi"), after a restart that line prints twice — render runs again from scratch. React 18 in dev StrictMode intentionally double-renders your components — surfacing this semantics on purpose. Not a bug, just Concurrent's physics.

三种"恢复"的真实代价 — 实测

Real cost of the three "resume" modes — measured

Suspense & Transitions — 异步的 first-class

Suspense & Transitions — async as first-class

抛 Promise · render 中断 · fallback 兜底

throw a Promise · pause render · fallback shown

Suspense 的实现机制极其反直觉——它用异常做控制流。当一个组件需要等异步数据，它抛出一个 Promise。Promise 沿调用栈往上传，被最近的 <Suspense> 边界捕获。边界把这棵子树打上"暂停"标记，渲染 fallback 占位。当 Promise resolve 时，该子树被重新调度一次 render。

Suspense's mechanism is wildly unintuitive — it uses exceptions as control flow. When a component needs async data, it throws a Promise. The Promise bubbles up to the nearest <Suspense> boundary, which marks that subtree as "paused" and renders the fallback. When the Promise resolves, that subtree is re-scheduled.

// React 19 use() · the actual signature is just "throw if not ready"
function use(usable) {
  if (usable !== null && typeof usable === 'object') {
    if (typeof usable.then === 'function') {
      switch (usable.status) {
        case 'fulfilled': return usable.value;
        case 'rejected':  throw usable.reason;
        default:           throw usable;          // ← suspends here
      }
    }
    if (usable.$$typeof === REACT_CONTEXT_TYPE) {
      return readContext(usable);
    }
  }
}

Transitions — 非阻塞 setState

Transitions — non-blocking setState

startTransition 把它内部的 setState 降级到 TransitionLane——这条 lane 比用户输入低，所以它的 render 可以被打断。最关键的：它在 render 期间不会触发 Suspense 兜底。当一棵子树在 transition 中等数据，React 会继续显示旧的 UI，直到新数据准备好——这就是 React 19 推崇的"pending UI 模式"，胜过 spinner。

startTransition demotes its setStates to a TransitionLane — lower than user input, so its render is interruptible. The critical property: during transition render, Suspense does not show its fallback. While the subtree awaits data, React keeps showing the old UI until the new one is ready. React 19's preferred "pending UI pattern" — beats a spinner.

function SearchBox() {
  const [query, setQuery] = useState('');
  const [pending, startTransition] = useTransition();
  const [deferred, setDeferred] = useState('');

  return <>
    <input value={query} onChange={e => {
      setQuery(e.target.value);          // ← Sync · 立即响应输入
      startTransition(() => {
        setDeferred(e.target.value);     // ← Transition · 慢的搜索结果
      });
    }} />
    {pending && <span>updating...</span>}
    <SearchResults query={deferred} /> // 用旧 query 渲染，新数据准备好后才换
  </>;
}

一次更新的时间线 — 把 13 步合到一张图

An update's timeline — 13 steps on one canvas

从 click 到 paint · 走完所有阶段

click → paint · every stage in one frame

把前面 13 章的每一步标到时间轴上——这是 React 19 处理一次同步用户输入（点击）的完整路径。整段过程在 M2 MacBook + Chrome 130 上的中位数约 1.2 ms。如果某一节超出预算，问题大概率出在用 console.log 标到的位置之一：

Plot every stage on a single axis — the full path of a React 19 sync user input (click). Median ~1.2 ms on M2 MacBook + Chrome 130. If a step blows its budget, the offender almost always lives at one of the labeled marks below:

Server Components — 把 Fiber 序列化送过来

Server Components — streaming a serialized Fiber

在服务器跑 render · 客户端只收"成品"

render on server · client receives the finished tree

RSC 不是 SSR——是把组件这个抽象本身切成两半。Server Component 跑在服务器 / build 时，永远不会出现在客户端 bundle 里。它的输出是一段"序列化的 React Element 流"——不是 HTML 字符串。客户端 React 解析这段流，把它和本地的 Client Component 拼起来，渲染出最终 UI。

RSC isn't SSR — it splits the component abstraction itself in two. A Server Component runs on the server or at build, never ships to the client bundle. Its output is a "serialized React-Element stream" — not HTML. The client React parses the stream, stitches it with local Client Components, and renders the final UI.

// 一个 Server Component (Next.js App Router)
async function UserPage({ id }) {
  const user = await db.users.findById(id);  // ← 在服务器直接 await
  return <section>
    <h1>{user.name}</h1>
    <EditButton userId={id} />  // ← 这是 Client Component, ships
  </section>;
}

// EditButton.jsx
'use client';
export function EditButton({ userId }) {
  const [editing, setEditing] = useState(false);  // ✅ ok, client
  return <button onClick={() => setEditing(true)}>Edit</button>;
}

RSC payload 长什么样

What the RSC payload looks like

服务器序列化输出的是一段React 内部 wire format——介于 JSON 和流式格式之间。每一行是一段独立的 "row"，浏览器收到第一行就可以开始渲染。这就是 RSC 自带流式 SSR能力的根因。

Server-side serialization produces React's own wire format — between JSON and a streaming format. Each line is one "row"; the browser starts rendering as soon as the first row arrives. RSC's streaming SSR comes for free from this.

// what the browser actually receives (simplified RSC payload)
0:[["$","section",null,{"children":[
  ["$","h1",null,{"children":"$1"}],         // $1 — pending data
  ["$","$L2",null,{"userId":42}]              // $L2 — client comp ref
]}]]
1:"Alice"                                     // data row resolves $1
2:I["./EditButton.js",["chunks/edit-x.js"],"EditButton"]  // client manifest

Wire format 全解剖 · 6 种 row 类型

Wire format · the 6 row types

RSC payload 是一个面向行的流——每一行是一个独立单元，客户端解析器（react-server-dom-webpack/client）拿到任意完整行就能消化掉。每行格式：ID:TYPE PAYLOAD\n。第一个字符决定 row 的类型——React 19 定义了 6 种。

RSC payload is a line-oriented stream — each line is a self-contained unit; the client parser (react-server-dom-webpack/client) consumes whole lines as they arrive. Format: ID:TYPE PAYLOAD\n. The first character of TYPE picks the row kind — React 19 defines 6.

Server Actions · 把"函数"发到客户端

Server Actions · shipping a "function" to the client

React 19 最大胆的设计是 Server Action——你在 Server Component 里定义一个 async 函数，把它绑给 <form action> 或 <button formAction>。客户端拿到的不是源码，而是一个引用。点按钮时，客户端 POST 一个请求到服务器，服务器查表跑这个函数。整套 RPC 机制对开发者完全透明。

React 19's boldest design is Server Actions: you define an async function inside a Server Component and bind it to <form action> or <button formAction>. The client doesn't receive the source — it receives a reference. On click, the client POSTs to the server; the server looks up and runs the function. The whole RPC machinery is invisible to the developer.

// app/page.jsx · Server Component
export default async function Page() {
  async function addTodo(formData) {
    'use server';                       // ← 标记 server action
    const text = formData.get('text');
    await db.todos.insert({ text });   // 直接读写数据库
    revalidatePath('/');                  // 自动重 render Server Component
  }

  return <form action={addTodo}>
    <input name="text" />
    <button>add</button>
  </form>;
}

// 客户端拿到的 RSC payload 里 addTodo 是这样:
//   "$F5"  ← Server Action 引用, ID = 5
// bundler 会为每个 'use server' 函数生成一个 ID + 注册到 manifest

Streaming SSR + Selective Hydration · 让 Suspense 真的能流式

Streaming SSR + Selective Hydration · making Suspense actually stream

React 18 给 SSR 注入了两个改变行业的能力：Streaming 和 Selective Hydration。两者协作让旧的"render-to-string-then-blast-everything"模式彻底失效。

React 18 added two industry-shifting capabilities to SSR: Streaming and Selective Hydration. Together they killed the old "render-to-string-then-blast-everything" model.

RSC payload 到 Fiber 树 · 客户端拼接的精确过程

RSC payload → Fiber tree · the client's exact assembly

前面看了 server 怎么发出 RSC payload，但客户端怎么把流式 row 拼回 Fiber 树这块还薄。这是 RSC 最不显但最关键的一段——它让"边收边渲染" 这件事真的发生。

We saw how the server emits RSC payload, but the harder question is: how does the client assemble streamed rows back into a Fiber tree? The least visible yet most critical part of RSC — it's what makes "render as you receive" actually happen.

三层（RSC / SSR / Streaming）的关系

RSC / SSR / Streaming · how they layer

三者最容易被搞混。一句话：SSR 解决"首屏 HTML 早出"，Streaming 解决"慢部分不拖累快部分"，RSC 解决"组件可以不送 JS"。它们可以独立使用、也可以组合——React 19 + Next.js 14 的标准栈是三者全开。

All three get confused. In one line: SSR makes the first HTML arrive sooner; Streaming keeps slow parts from blocking fast parts; RSC means components don't need to ship JS. They can stack — React 19 + Next.js 14's default stack runs all three.

'use client' 是个边界标记 — bundle graph 长这样

'use client' is a boundary marker — the bundle graph

很多人以为 'use client' 是"把这个文件下发到客户端"——其实它是"把这个文件标成客户端入口"。bundler (Webpack / Turbopack / Vite) 看到这个指令, 会把这个文件 + 它所有静态依赖切到 client bundle, 同时在父侧 (server) 留一个占位 reference。RSC 序列化时, 这个 reference 变成 "$Lid" 行——告诉客户端"这里放一个 EditButton, manifest 第 id 项"。

It's tempting to think 'use client' means "send this file to the client". It actually means "this file is a client entry". The bundler (Webpack / Turbopack / Vite) treats the marked file plus all its static imports as the client bundle, and leaves a placeholder reference on the server side. When RSC serializes, that reference becomes a "$Lid" row — telling the client "put an EditButton here, manifest entry id".

客户端解码 — 一行 wire format 怎么变成一棵 fiber

Client decode — how one wire row turns into a fiber

客户端 React (react-server-dom-webpack/client) 拿到 RSC payload 的每一行, 跑一遍解码 pipeline——这条 pipeline 是 RSC 性能模型的核心。下面这张图把单行 row 从字节流到 fiber 节点的全过程拉直了画:

Client-side React (react-server-dom-webpack/client) runs each row of the RSC payload through a decode pipeline — the heart of RSC's performance model. This figure unrolls a single row from byte stream to fiber node:

Server Action — 一次往返的真实时间线

Server Action — the round-trip in time

Server Action 写法看着像本地函数, 实际上是声明式 RPC: 你写 <form action={addTodo}>, bundler 把 addTodo 替换成"POST 到某个 endpoint"的薄包装。下面这张图把一次 Server Action 提交的 6 个阶段拉到一条时间线上, 每段标注谁(浏览器/网络/服务器)花了多少 ms。

Server Actions look like local functions; they're declarative RPCs. You write <form action={addTodo}>; the bundler replaces addTodo with a thin wrapper that POSTs to an endpoint. This figure lays the 6 phases on one timeline, each labelled by who's working (browser / network / server) and for how many ms:

Streaming chunk 注入 — Suspense 怎么和 RSC 协作

Streaming chunk injection — how Suspense and RSC cooperate

RSC 真正的杀手锏不只是"组件不发 JS",而是渐进式注入——服务器一边算一边发,Suspense 边界遇到 pending Promise 时先发个 placeholder, 数据 ready 后追加一行把 placeholder 替换掉。客户端无需"等整页 ready", 也无需"SSR 完一次 HTML, hydrate 再 fetch 一次"——所有进展都来自同一条 HTTP 流。

RSC's real superpower isn't just "some components ship no JS" — it's progressive injection. The server streams as it computes; at every Suspense boundary it emits a placeholder first, then tacks on another row later that replaces the placeholder when data is ready. The client never has to "wait for the whole page" or "SSR HTML once, hydrate, then fetch again" — all progress comes from one HTTP stream.

React 19 — use · Actions · Compiler · Owner Stacks

React 19 — use · Actions · Compiler · Owner Stacks

2024-26 的四件大事

the four big shipments of 2024-26

React Compiler 做了什么

What React Compiler does

看下面这段 Counter 子组件：

Take this Counter helper:

// before — 手写优化
function Display({ count }) {
  const doubled = useMemo(() => count * 2, [count]);
  const onClick = useCallback(() => log(count), [count]);
  return <Big value={doubled} onClick={onClick} />;
}

// after — compiler 接管
function Display({ count }) {
  const doubled = count * 2;
  const onClick = () => log(count);
  return <Big value={doubled} onClick={onClick} />;
}
// ← compiler 在编译期自动加上 cache 槽，等价于上面那段，
//   但你不需要写 useMemo / useCallback。

Compiler 用静态分析识别"同输入同输出"的纯片段，自动给它们生成等价的 useMemo 代码。在 Meta 内部的 200+ 个 React 应用上，平均能消除 35-45% 的不必要 render。它不是 React 的运行时——产物是普通 JS。

The Compiler uses static analysis to detect "same input → same output" pure regions and emits equivalent useMemo code. Across Meta's 200+ React apps, it eliminates 35-45% of unnecessary renders. It is not a React runtime — output is plain JS.

Compiler 的 IR · Memo Map

Compiler's IR · the Memo Map

"编译器" 听起来神秘——其实 React Compiler 就是个 babel plugin。它分三步走：① 解析 AST 找出"纯"函数体（无外部 mutation, 无 ref read）；② 建立依赖图，把每个表达式标注它依赖哪些 props/state/hook；③ 生成代码，在函数顶部插入一个 cache 数组, 把每个表达式按依赖签名挂上 cache slot。

"Compiler" sounds mystical — but React Compiler is just a babel plugin. Three steps: ① parse AST to find "pure" function bodies (no external mutation, no ref read); ② build dependency graph annotating each expression with its props/state/hook deps; ③ emit code with a cache array at the top of the function and each expression hung on a slot keyed by its deps signature.

// ① 编译输入
function Display({ count }) {
  const doubled = count * 2;
  const onClick = () => log(count);
  return <Big value={doubled} onClick={onClick} />;
}

// ② Compiler 内部 IR (Memo Map · 简化展示)
{
  cache_slots: 3,
  bindings: {
    "doubled": { expr: "count * 2", deps: ["count"], slot: 0 },
    "onClick": { expr: "() => log(count)", deps: ["count"], slot: 1 },
    "$result": {
      expr: "<Big value={doubled} onClick={onClick} />",
      deps: ["doubled", "onClick"],
      slot: 2
    }
  }
}

// ③ 实际输出 (运行时代码)
function Display({ count }) {
  const $ = useMemoCache(3);                // 3 个 cache slot
  let doubled;
  if ($[0] !== count) {                  // deps 比对
    doubled = count * 2;
    $[0] = count; $[1] = doubled;
  } else {
    doubled = $[1];
  }
  let onClick;
  if ($[2] !== count) {
    onClick = () => log(count);
    $[2] = count; $[3] = onClick;
  } else {
    onClick = $[3];
  }
  // ... result 同样 cache
}

注意 useMemoCache(3)——这是 React 19 给 Compiler 留的新原语。它返回一个挂在 fiber 上的数组，跨 render 稳定。比起一堆 useMemo 节省了大量 hook 节点（一个数组替代 N 个 hook）。

Note useMemoCache(3) — a new primitive React 19 reserved for the Compiler. Returns an array hanging on the fiber, stable across renders. Saves many hook nodes (one array vs N hook entries) compared to spamming useMemo.

Memo Map 的失效传播 · 一个细胞坏了整个表怎么办

Memo Map invalidation · what happens when one cell goes stale

Memo Map 不是简单的"一个 dep 变就重算这个 expr"——它建立了依赖图。如果 doubled 的依赖 count 变了, 那么引用了 doubled的所有下游表达式 (比如 $result 用了 doubled) 也要重算。Compiler 在编译期就把这个传播图算清楚——运行时只是按图查表。

Memo Map isn't a simple "dep changed → recompute this expr" — it's a dependency graph. If doubled's dep count changed, every downstream expression referencing doubled (e.g. $result using doubled) must also recompute. The Compiler resolves this propagation at compile time — runtime is just a lookup.

// Compiler 编译期建立的传播图 (内部 IR · 简化展示)
{
  count: { upstream: ["props"], downstream: ["doubled", "onClick"] },
  doubled: { upstream: ["count"], downstream: ["$result"] },
  onClick: { upstream: ["count"], downstream: ["$result"] },
  $result: { upstream: ["doubled", "onClick"], downstream: [] }
}

// 运行时: count 变 → 自动失效 doubled + onClick → 级联失效 $result
// 注意: Compiler 不跑这个图, 它把每个表达式的 dep 比对编译进代码
// 输出的运行时代码是展开后的 if-else 链, 不是动态图遍历

function Display({ count }) {
  const $ = useMemoCache(6);   // 3 个 expr × 2 槽 (dep + value)
  let doubled, onClick, result;

  if ($[0] !== count) {        // 失效检查 1
    doubled = count * 2;
    onClick = () => log(count);
    $[0] = count;
    $[1] = doubled;
    $[2] = onClick;            // ★ doubled 和 onClick 是同时失效的 (因为同一个 dep)
  } else {
    doubled = $[1];
    onClick = $[2];
  }

  if ($[3] !== doubled || $[4] !== onClick) {   // 失效检查 2 (依赖上层结果)
    result = <Big value={doubled} onClick={onClick} />;
    $[3] = doubled; $[4] = onClick; $[5] = result;
  } else {
    result = $[5];
  }
  return result;
}

Compiler escape hatch · 三种"别管这段" 指令

Compiler escape hatches · three "hands off" directives

100% 自动优化的编译器不存在——总会有 Compiler 推不出来或推错的边角。React Compiler 提供三个 escape hatch:

A 100%-automatic optimizing compiler doesn't exist — corner cases will always slip through or get misanalyzed. React Compiler ships three escape hatches:

// ① "use no memo" 指令字符串 · 函数级关闭
function Display({ count }) {
  "use no memo";        // ← 整个 Display 不被 Compiler 处理
  ...
}

// ② // @no-memo 注释 · 行级跳过
function Display({ count }) {
  // @no-memo
  const manualThing = expensive(count);  // 这一行不 cache
  ...
}

// ③ Compiler 自动放弃 · "bail out"
function Display({ count }) {
  globalCounter++;            // 全局 mutation → Compiler 检测到 → 整函数 bail out
  ref.current = true;        // ref read/write → 同样 bail out
  try { } catch {}            // 复杂控制流 → bail out
  ...
}
// dev 模式下 console 会告诉你哪些组件被 bail out 了

实测性能 · Meta 200 应用的真实数字

Real perf · numbers from Meta's 200+ apps

Owner Stacks · 实现机制

Owner Stacks · how it's implemented

React 19 的 Owner Stacks 看起来魔法——错误信息里能显示"Avatar 被 UserCard 渲染、UserCard 被 DashboardPage 渲染"。秘密在 Fiber 的两个字段：_debugOwner 和 _debugSource（dev 才存在）。

React 19's Owner Stacks look magical — error messages show "Avatar was rendered by UserCard, UserCard by DashboardPage". The secret is two Fiber fields: _debugOwner and _debugSource (dev-only).

// dev 模式下, 每个 createElement 调用都被埋入 owner
function createElement(type, config, ...children) {
  ...
  if (__DEV__) {
    element._owner = ReactCurrentOwner.current;
    // ★ ReactCurrentOwner 是个全局指针, 当前 render 函数对应的 Fiber
  }
  return element;
}

// renderWithHooks 在调用 Component() 前后维护这个指针:
function renderWithHooks(current, wip, Component, props) {
  ...
  ReactCurrentOwner.current = wip;       // ← 设置 owner
  const children = Component(props);     // ← createElement 调用此期间发生
  ReactCurrentOwner.current = null;     // ← 复位
}

// 当错误抛出时, React 沿 fiber._debugOwner 链生成 stack
function getOwnerStackByFiberInDev(fiber) {
  let stack = '';
  let current = fiber;
  while (current) {
    stack += `\n    at ${getComponentName(current)} (${current._debugSource})`;
    current = current._debugOwner;       // ← 不是 .return! 是 owner
  }
  return stack;
}

注意一个微妙之处：_debugOwner 不等于 return。return 是结构父——谁包含这个节点; _debugOwner 是渲染父——谁的 render 函数创建了这个节点。同一个组件可能被 N 个不同的 owner 渲染（比如 forwardRef 转发）。Owner stack 跟踪"创建之路"而非"位置之路"，所以才有调试价值——它告诉你"这个 Bug 在我的代码里哪"。

Subtle point: _debugOwner is not the same as return. return is the structural parent — what contains the node; _debugOwner is the rendering parent — whose render created the node. A single component can be rendered by N different owners (forwardRef forwarding, for instance). Owner stack traces the "creation path", not the "position path" — which is what makes it debuggable: it answers "where in MY code is this bug".

// 一个例子 · return ≠ owner
function Wrapper({ children }) {
  return <div className="wrap">{children}</div>;
}

function Page() {
  return <Wrapper><Avatar /></Wrapper>;
}

// 对 Avatar fiber:
//   fiber.return → div (它的结构父是 Wrapper 里的 div)
//   fiber._debugOwner → Page (它的渲染父是 Page, 不是 Wrapper)

// React 18: error stack 显示 Wrapper → 让你以为是 Wrapper 写错了
// React 19: error stack 显示 Page → 准确指出是 Page 调用错

症状反查 — 现场问题对应到哪一章

Symptom lookup — pin a real bug to a chapter

debug 手册 · 把症状映射到流水线节点

a debug manual that maps symptoms to pipeline nodes

Hydration Mismatch — 一张专门的诊断图

Hydration mismatch — a dedicated debug map

SSR / RSC 时代最常见的错误 #418, #419, #423

errors #418, #419, #423 — the most common bugs of the SSR / RSC era

"Hydration mismatch"是 SSR/RSC 项目里出现频率最高的 React 警告——但它的诊断路径散落在文档、博客、Discord 答疑中, 从来没有一张完整的"看到这条错就走这条流程"图。这一章补上。

"Hydration mismatch" is the most common React warning in SSR/RSC projects — yet its diagnostic path is scattered across docs, blog posts, and Discord threads. There's never been one complete "see this error → walk this flowchart" map. Here it is.

实战 · React DevTools Profiler

Field practice · React DevTools Profiler

flamegraph · ranked · why did this render · owner stacks

flamegraph · ranked · why did this render · owner stacks

从这一章起进入"field 章节"——不讲原理，讲怎么抓现行。React DevTools Profiler 是第一线索：它告诉你React 自己觉得哪里慢、为什么 render。它不告诉你浏览器有没有问题（那是下一章 Chrome Performance 的活）。两个工具配合，覆盖 95% 的现场。

From here we shift to "field chapters" — not theory, but how to catch problems in the wild. React DevTools Profiler is the first lead: it tells you what React itself thinks is slow and why a render happened. It does not tell you about the browser's behavior (that's next chapter). Together they cover 95% of cases.

Profiler 在抓什么

What Profiler actually captures

点 record → 操作页面 → 停止。这段时间里 React 把每一次 commit 都记下来：哪些 fiber 被 render 了、各自耗时、render 原因、是否 bail-out。Profiler 不抓 commit 之间的"空闲"——只抓 React 真的在干活的瞬间。

Press record → interact → stop. React records every commit in that window: which fibers rendered, how long each took, the render reason, whether bail-out fired. Profiler doesn't capture the "idle" gaps between commits — only the moments React is actually working.

"Why did this render?" 的四种答案

The four answers to "why did this render?"

React 给你的原因列表只有四种可能。背熟它，看 Profiler 就如读字典：

React's reason list has exactly four entries. Memorize them; Profiler becomes a dictionary lookup:

Owner Stacks · React 19 引入的"谁渲染了我"

Owner Stacks · React 19's "who rendered me"

2026 年的 React DevTools 一打开就显示组件嵌套链而不是 JS 调用栈。错误信息里也是：从此你能看到"App → DashboardPage → UserCard → Avatar"，而不是无穷的 renderWithHooks。这是 React 16 以来调试体验最大的一次提升。

React DevTools in 2026 shows the component nesting chain instead of the JS call stack. Same in error messages. You see "App → DashboardPage → UserCard → Avatar" instead of an endless ladder of renderWithHooks frames. The biggest debug-experience win since React 16.

// React 18 error:
TypeError: Cannot read property 'name' of undefined
  at renderWithHooks (react-dom.js:14782:18)
  at mountIndeterminateComponent (react-dom.js:17811:13)
  at beginWork (react-dom.js:19049:16)
  ... 50 more identical frames ...

// React 19 error (with Owner Stacks):
TypeError: Cannot read property 'name' of undefined
  at Avatar (Avatar.tsx:7)
  at UserCard (UserCard.tsx:14)        // ← rendered me
  at DashboardPage (DashboardPage.tsx:23) // ← rendered them
  at App (App.tsx:4)

实战 · Chrome Performance & 火焰图

Field practice · Chrome Performance & flame charts

user timings · long tasks · layout thrashing · 浏览器视角

user timings · long tasks · layout thrashing · browser view

React DevTools 告诉你 React 自己慢不慢，但它的视角止于 commit——browser 内部的 layout、style 重算、paint、GC、image decode 它都看不见。Chrome Performance 是另一只眼睛：它看主线程一切，包括 React 跑、浏览器跑、第三方脚本跑。两个工具像 X 光和 MRI——拍同一个病人但成像原理不同。

React DevTools tells you whether React itself is slow, but its lens stops at commit — browser internals (layout, style recalc, paint, GC, image decode) are invisible. Chrome Performance is the other eye: it sees everything on the main thread — React, browser, third-party scripts. The two tools are like X-ray and MRI — same patient, different imaging.

React 18+ 自动注入的 User Timings

User Timings React 18+ auto-injects

React 18 之后不再需要装"Why Did You Render"或 React Profiler 数据导出。React 自己在每次 render 和 commit 时调 performance.measure(...)——这些 mark 在 Chrome Performance 的 Timings 轨道里直接可见。在 Components track 里还能看到每个组件的 render 区段。这两个 track 是 React 19 + Chrome 130 之后不需要任何额外配置就能用的现场工具。

From React 18 you don't need "Why Did You Render" or exported Profiler data. React itself calls performance.measure(...) around every render and commit — the marks appear in Chrome Performance's Timings track. The Components track shows per-component render spans. As of React 19 + Chrome 130, zero config required.

区分"React 慢"vs"浏览器慢"

Telling "React slow" from "browser slow"