❌

普通视图

发现新文章，点击刷新页面。
昨天以前首页

React 19.x 的 lazy 与 Suspense

✇掘金 前端
作者 米丘
2026年5月28日 18:26

React.lazy

在构建大型 React 应用时，打包体积过大往往会影响首屏加载速度。React.lazy 正是为了解决这一问题而诞生的内置函数，它让你可以将组件动态导入（code splitting），并按需加载，从而显著提升应用性能。

为何使用 React.lazy？

  1. 减少初始包体积：应用的首屏可能不需要所有组件。通过代码分割，只加载当前路由或交互所需的组件。
  2. 提升首屏加载速度：更少的 JavaScript 意味着更快的解析和执行时间，改善用户体验。
  3. 优化缓存与带宽：用户可能只使用部分功能，懒加载未使用的代码可节省流量。
  4. 与 Suspense 天然集成：React.lazy 配合 Suspense 可以优雅地显示加载状态（如 Loading 动画）。

渲染阶段流程

React.lazy 组件加载完成的触发机制依赖于 Promise 的 resolve 回调 和 React 内部的 Suspense 重试（ping）机制。

一、 初始化

调用 React.lazy(() => import('./Component')) 会生成一个特殊的“懒加载对象”，内部包含 _status（初始为 Uninitialized）和 _result（存储加载器函数）。

二、 首次渲染

当 React 遇到这个懒加载对象时，会调用内部函数 lazyInitializer：

  • 执行 _result()（即 import()），得到一个 Promise（thenable）。
  • 将 _status 更新为 Pending，_result 指向该 Promise。
  • 抛出该 Promise 以触发最近的 <Suspense> 边界.

三、 suspense 捕获与监听

React 捕获抛出的 Promise，向上查找 Suspense 边界：

  • 调用 attachPingListener 为该 Promise 添加一个 then 回调（即 ping 函数）。
  • 该边界立即渲染 fallback UI。

四、 加载完成（Promise resolve）

当动态导入的模块成功加载后，Promise 被 resolve，模块对象作为结果返回。Promise 的回调执行：

  • 将 lazy 对象的 _status 更新为 Resolved，_result 替换为模块对象。
  • 调用之前附加的 ping 回调（实际上是 pingSuspendedRoot）。

五、 触发重新渲染

pingSuspendedRoot 会标记对应根节点的优先级车道（pingedLanes），并调用 ensureRootIsScheduled，重新调度整个应用的渲染（或仅重试该 Suspense 边界）。

六、 二次渲染

React 再次执行该组件的渲染逻辑，此时 lazyInitializer 发现 _status === Resolved，直接返回 _result.default（真正的组件），从而正常完成渲染，替换 fallback。

注意事项

  1. 避免在渲染函数内动态调用 lazy：lazy 应在模块顶层定义，确保每次渲染都得到相同的引用。
  2. 重复导入优化：同一个 lazy 组件在多处使用时，内部会共享相同的 Promise，不会重复加载。
  3. 错误处理：懒加载可能因网络问题失败，建议结合错误边界（Error Boundary）捕获加载失败错误。
  4. 命名导出问题：默认导出是 lazy 的约定，非默认导出需手动转换。
  5. 避免在 Suspense 外部调用 lazy 组件：否则无法捕获挂起。

示例 懒加载组件

lazy 接收一个函数，该函数必须返回一个动态 import() 调用（返回 Promise，其 resolve 值为包含 React 组件的模块）。Suspense 用于包裹懒加载组件，并在等待期间渲染 fallback 内容。

import { lazy, Suspense, useState } from "react";

const Card = lazy(() => import("./Card"));
const SuspenseB = () => {
  const [num, setNum] = useState(0);
  return (
    <div className="suspense-b">
      <p>num: {num}</p>
      <button onClick={() => setNum(num + 1)}>click</button>
      <Suspense fallback={<div className="suspense-b-fallback">Loading...</div>}>
        <Card />
      </Suspense>
    </div>
  );
};
export default SuspenseB;

懒加载组件开始到成功的 三个阶段

初始化 状态 -1

image.png

加载中 状态 0

image.png

加载完成 状态 1

image.png

import {  useState, } from "react";

const Card = () => {
  const [count, setCount] = useState(0);
  return (
    <div className="card">
      <p>Count: {count}</p>
      <button onClick={() => setCount((val) => val + 1)}>Click me</button>
    </div>
  );
};

export default Card;

调用 React.lazy(() => import('./Component')) 会生成一个特殊的“懒加载对象”，内部包含 _status（初始为 Uninitialized）和 _result（存储加载器函数）。

image.png

image.png

beginWork

image.png

fiber.elementType

image.png

resolveLazy 解析 lazy 组件

image.png

lazy._init(lazy._payload) 执行初始化函数

image.png

回到 resolveLazy 解析 lazy 组件

全局变量 suspendedThenable 为 promise pending状态

image.png

 const SuspenseException: mixed = new Error(
  "Suspense Exception: This is not a real error! It's an implementation " +
    'detail of `use` to interrupt the current render. You must either ' +
    'rethrow it immediately, or move the `use` call outside of the ' +
    '`try/catch` block. Capturing without rethrowing will lead to ' +
    'unexpected behavior.\n\n' +
    'To handle async errors, wrap your component in an error boundary, or ' +
    "call the promise's `.catch` method and pass the result to `use`.",
);

handleThrow 负责处理渲染过程中抛出的各种异常（包括普通错误和 Suspense 挂起）

image.png

getSuspendedThenable

全局变量重置 为 null ,返回 promise pending

image.png

回到 handleThrow

image.png

renderRootSync

全局变量 workInProgressSuspendedReason 为 3, 代表 SuspendedOnImmediate 因任务立即挂起

image.png

找到边界

image.png

// 未挂起，正常渲染
const NotSuspended: SuspendedReason = 0;
// 渲染过程中抛出异常
const SuspendedOnError: SuspendedReason = 1;
// 等待异步数据
const SuspendedOnData: SuspendedReason = 2;
// 因立即任务挂起
const SuspendedOnImmediate: SuspendedReason = 3;
// 因实例挂起
const SuspendedOnInstance: SuspendedReason = 4;
// 因实例挂起但准备继续
const SuspendedOnInstanceAndReadyToContinue: SuspendedReason = 5;
// 因废弃的 Promise 挂起
const SuspendedOnDeprecatedThrowPromise: SuspendedReason = 6;
// 挂起准备继续
const SuspendedAndReadyToContinue: SuspendedReason = 7;
// 因 hydration 挂起
const SuspendedOnHydration: SuspendedReason = 8;
// 因 action 挂起
const SuspendedOnAction: SuspendedReason = 9;

throwAndUnwindWorkLoop 处理渲染过程中的异常/挂起，展开栈并找到处理边界

image.png

throwException 处理渲染阶段的异常和 Suspense

image.png

attachPingListener 为 Suspense 边界的挂起 Promise（wakeable）添加“ping”监听器

image.png

渲染 fallback

再次进入 ,lazy组件还是加载中

image.png

懒加载组件加载完成

image.png

加载完毕是一个函数组件

image.png

示例 命名导出组件的懒加载

const InfoCard = lazy(() =>
  import("./Card").then((mod) => ({ default: mod.InfoCard })),
);

export const InfoCard = () => {
  const [count, setCount] = useState(0);
  return (
    <div className="info-card">
      <p>Info Card</p>
      <button onClick={() => setCount((val) => val + 1)}>
        InfoCard-Click me
      </button>
      <p>InfoCard Count: {count}</p>
    </div>
  );
};

beginWork 阶段

fiber.tag = 16 , 代表 LazyComponent

case LazyComponent: {
  const elementType = workInProgress.elementType;
  return mountLazyComponent(
    current,
    workInProgress,
    elementType,
    renderLanes,
  );
}

image.png

completeWork 阶段

case LazyComponent:
case SimpleMemoComponent:
case FunctionComponent:
case ForwardRef:
case Fragment:
case Mode:
case Profiler:
case ContextConsumer:
case MemoComponent:
  bubbleProperties(workInProgress);
  return null;

源码

const Uninitialized = -1; // 未初始化，未调用
const Pending = 0; // 加载中
const Resolved = 1; // 加载成功
const Rejected = 2; // 加载失败

function lazy<T>(
  ctor: () => Thenable<{default: T, ...}>,
): LazyComponent<T, Payload<T>> {

  // 创建 payload 对象
  const payload: Payload<T> = {
    // We use these fields to store the result.
    _status: Uninitialized, // 初始化，未调用
    _result: ctor, // 存储工厂函数
  };

  // 创建 lazyType 对象   
  const lazyType: LazyComponent<T, Payload<T>> = {
    $$typeof: REACT_LAZY_TYPE, // 标识是 lazy 组件
    _payload: payload, // 存储 payload 对象，加载信息
    _init: lazyInitializer, // 初始化函数
  };

  return lazyType;
}
  • 未初始化状态（_status === Uninitialized）,状态变为 Pending,执行 throw payload._result;，抛出 thenable。这正是 React Suspense 的触发点。
  • 成功回调：当模块加载成功时，将 payload._status 设置为 Resolved，payload._result 设置为模块对象。
  • 失败回调：将 payload._status 设置为 Rejected，payload._result 设置为错误对象。如果是 Rejected，抛出错误，由最近的错误边界（Error Boundary）捕获
function lazyInitializer<T>(payload: Payload<T>): T {
  // 未初始化处理
  if (payload._status === Uninitialized) {
    let resolveDebugValue: (void | T) => void = (null: any);
    let rejectDebugValue: mixed => void = (null: any);
    const ctor = payload._result; // 加载器函数 （） => import("")
    const thenable = ctor(); // 加载器函数返回的 Thenable 对象

    // 监听 Promise 状态变化
    thenable.then(
      moduleObject => { // 加载成功
        // 正在加载、未初始化
        if (
          (payload: Payload<T>)._status === Pending ||
          payload._status === Uninitialized
        ) {
          // Transition to the next state.
          const resolved: ResolvedPayload<T> = (payload: any);
          resolved._status = Resolved; // 设置状态为加载成功
          resolved._result = moduleObject; // 设置结果为模块对象


          if (thenable.status === undefined) {
            const fulfilledThenable: FulfilledThenable<{default: T, ...}> =
              (thenable: any);
            fulfilledThenable.status = 'fulfilled'; // 设置状态为加载成功
            fulfilledThenable.value = moduleObject; // 设置值为模块对象
          }
        }
      },
      // 加载失败
      error => {
        if (
          (payload: Payload<T>)._status === Pending ||
          payload._status === Uninitialized
        ) {
          // Transition to the next state.
          const rejected: RejectedPayload = (payload: any);
          rejected._status = Rejected; // 设置状态为加载失败
          rejected._result = error; // 设置结果为错误对象
 
          if (thenable.status === undefined) {
            const rejectedThenable: RejectedThenable<{default: T, ...}> =
              (thenable: any);
            rejectedThenable.status = 'rejected';
            rejectedThenable.reason = error;
          }
        }
      },
    );


    // 未初始化
    if (payload._status === Uninitialized) {
      const pending: PendingPayload = (payload: any);
      pending._status = Pending;
      pending._result = thenable;
    }
  }
  // 加载成功
  if (payload._status === Resolved) {
    const moduleObject = payload._result;
    return moduleObject.default; // 返回模块对象的默认导出
    
  } else {
   // 抛出 thenable。这正是 React Suspense 的触发点
    throw payload._result;
  }
}

Suspense

Suspense 是 React 内置的组件，用于包裹那些可能“挂起”（Suspend）的子组件。当子组件抛出 Promise（或 React 内部的 Suspense 异常）时，Suspense 会捕获并渲染 fallback 属性指定的占位内容，直到 Promise 解决后重新渲染子组件。

suspense 能够实现：

  • 并行等待多个资源。
  • 避免加载闪烁（快速加载时不显示 fallback）。
  • 与错误边界（Error Boundary）无缝集成。

注意事项

  1. 避免在 fallback 中再使用 Suspense
  2. Suspense 不能捕获错误 。它只处理 Promise 挂起，普通错误（如运行时错误）需要 Error Boundary。

beginWork

Suspense 组件会根据是否已捕获挂起（DidCapture 标记）或需要停留在 fallback 状态，决定本次渲染显示 fallback 还是 primary 内容：

  • 若需显示 fallback，则创建 fallback 子树并将 primary 子树包裹为隐藏的 Offscreen 组件以保留状态。
  • 否则正常渲染 primary 子树。
case SuspenseComponent:
      return updateSuspenseComponent(current, workInProgress, renderLanes);

completeWork

Suspense 组件负责完成水合收尾（处理 SSR 脱水节点）、处理 DidCapture 标记以触发重新渲染 fallback、调度重试队列（为等待的 Promise 附加 ping 监听器），并标记因 fallback/primary 切换而产生的副作用（如添加 Visibility 或 Passive 标记），最后向上冒泡 childLanes。

commit 阶段

Mutation 子阶段：

  • 通过 Offscreen 组件的 Visibility 标记，对 primary 树执行 display: none（隐藏）或恢复显示。
  • 处理边界删除时的清理工作（解绑 ref、调用 componentWillUnmount）。
  • 清空已完成的重试队列。

Layout 子阶段：

  • 执行 scheduleRetryEffect 中调度的重试回调：为 retryQueue 中的每个 Promise 附加 ping 监听器（pingSuspendedRoot）。
  • 允许子组件（primary 或 fallback）正常执行 useLayoutEffect 和 componentDidMount/Update。

Passive 阶段（异步）：

  • 执行 Offscreen 子树上因可见性变化而挂起的 useEffect 清理和回调。

示例 代码分割

import { lazy, Suspense, useState } from "react";

const Card = lazy(() => import("./Card"));
const SuspenseB = () => {
  const [num, setNum] = useState(0);
  return (
    <div className="suspense-b">
      <p>num: {num}</p>
      <button onClick={() => setNum(num + 1)}>click</button>
      <Suspense fallback={<div className="suspense-b-fallback">Loading...</div>}>
        <Card />
      </Suspense>
    </div>
  );
};
export default SuspenseB;

beginWork updateSuspenseComponent

当前正在处理 workInprocess 是 suspense 组件，有属性pendingProps包含children 和 fallback，current为 null

image.png

image.png

mountSuspensePrimaryChildren

直接渲染 primary fiber

mountWorkInProgressOffscreenFiber 创建 Offscreen fiber

image.png

这里return，结束当前的beginWork

image.png

来到 beginWork updateOffscreenComponent

此时 workInProcess 为 Offscreen fiber,(之前 suspense要渲染的primary fiber），current 为 null

image.png

首次挂载创建 Offscreen 实例，用于存储 Offscreen 的可见性、待处理的标记、重试缓存及相关 transitions

image.png

image.png

reconcileChildren 子节点

createFiberFromTypeAndProps 创建 lazy fiber

return，又结束此次 beginWork

image.png

来到 beginWrok lazy fiber

image.png

在解析懒加载组件时，会 有微任务产生

进入 beginWork tag 为13 suspense

image.png

支持显示 fallback

挂载 primary fiber，mode 为隐藏状态

image.png

创建 fallback fiber，类型为 Fragment

image.png

关系

workInProcess.child 为 primary fiber

primary fiber的 sibling 为 fallback fiber

image.png

image.png

image.png

beginWork 结束，再次进入beginWork 处理 fallback fiber

当 lazy 加载完成后，继续处理

示例 数据获取 use

import { use, useState, Suspense } from "react";

const fetchData = (async () => {
  const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
  return response.json();
})();

const SuspenseC = () => {
  const result = use(fetchData);
  const [count, setCount] = useState(0);

  console.log("state-a-render-----");

  return (
    <div className="state-a">
      <h3>StateA</h3>
      <p>{result?.title}</p>
      <p>当前count: {count}</p>
      <button onClick={() => setCount(count + 1)}>SuspenseC -点击增加</button>
    </div>
  );
};

const App = () => {
  return (
    <Suspense fallback={<div className="suspense-c-fallback">Loading...</div>}>
      <SuspenseC />
    </Suspense>
  );
};
export default App;

最后

❌
❌