React 性能跟踪

这些轨道旨在通过可视化 React 特定的事件和指标以及其他关键数据源（例如网络请求、JavaScript 执行和事件循环活动），为开发者提供对 React 应用性能的全面洞察，所有这些都同步在“性能”面板中的统一时间轴上，以便全面了解应用行为。

¥These tracks are designed to provide developers with comprehensive insights into their React application’s performance by visualizing React-specific events and metrics alongside other critical data sources such as network requests, JavaScript execution, and event loop activity, all synchronized on a unified timeline within the Performance panel for a complete understanding of application behavior.

• 用法
  • 使用性能分析构建
• 跟踪
  • 调度程序
  • 组件
  • 服务器

---

用法

¥Usage

React 性能轨迹仅在 React 的开发和性能分析版本中可用：

¥React Performance tracks are only available in development and profiling builds of React:

• 开发：默认启用。

  ¥Development: enabled by default.

• 性能分析：默认情况下，仅启用 Scheduler 轨道。组件轨道仅列出使用 <Profiler> 封装的子树中的组件。如果你启用了 React 开发者工具扩展，则所有组件都会包含在组件轨道中，即使它们未封装在 <Profiler> 中。服务器轨道在性能分析构建中不可用。

  ¥Profiling: Only Scheduler tracks are enabled by default. The Components track only lists Components that are in subtrees wrapped with <Profiler>. If you have React Developer Tools extension enabled, all Components are included in the Components track even if they’re not wrapped in <Profiler>. Server tracks are not available in profiling builds.

如果启用，轨道应该会自动出现在你使用提供 可扩展 API 的浏览器的性能面板记录的轨迹中。

¥If enabled, tracks should appear automatically in the traces you record with the Performance panel of browsers that provide extensibility APIs.

使用性能分析构建

¥Using profiling builds

除了生产和开发版本之外，React 还包含一个特殊的性能分析版本。要使用性能分析构建，必须使用 react-dom/profiling 而不是 react-dom/client。我们建议你在构建时通过 bundler 别名将 react-dom/client 别名为 react-dom/profiling，而不是手动更新每个 react-dom/client 导入。你的框架可能内置了对 React 性能分析构建的支持。

¥In addition to production and development builds, React also includes a special profiling build. To use profiling builds, you have to use react-dom/profiling instead of react-dom/client. We recommend that you alias react-dom/client to react-dom/profiling at build time via bundler aliases instead of manually updating each react-dom/client import. Your framework might have built-in support for enabling React’s profiling build.

---

跟踪

¥Tracks

调度程序

¥Scheduler

调度程序是 React 内部概念，用于管理具有不同优先级的任务。此轨道包含 4 个子轨道，每个子轨道代表特定优先级的工作：

¥The Scheduler is an internal React concept used for managing tasks with different priorities. This track consists of 4 subtracks, each representing work of a specific priority:

• 阻塞 - 同步更新，可能由用户交互发起。

  ¥Blocking - The synchronous updates, which could’ve been initiated by user interactions.

• 转换 - 在后台执行的非阻塞工作，通常通过 startTransition 发起。

  ¥Transition - Non-blocking work that happens in the background, usually initiated via startTransition.

• 暂停 - 与 Suspense 边界相关的工作，例如显示 fallback 或显示内容。

  ¥Suspense - Work related to Suspense boundaries, such as displaying fallbacks or revealing content.

• 空闲 - 当没有其他优先级更高的任务时，优先级最低的工作会被执行。

  ¥Idle - The lowest priority work that is done when there are no other tasks with higher priority.

渲染

¥Renders

每个渲染过程都包含多个阶段，你可以在时间轴上看到这些阶段：

¥Every render pass consists of multiple phases that you can see on a timeline:

• 更新 - 这就是导致新的渲染过程的原因。

  ¥Update - this is what caused a new render pass.

• 渲染 - React 通过调用组件的渲染函数来渲染更新后的子树。你可以在 组件轨道 上看到渲染的组件子树，它遵循相同的配色方案。

  ¥Render - React renders the updated subtree by calling render functions of components. You can see the rendered components subtree on Components track, which follows the same color scheme.

• 提交 - 渲染组件后，React 会将更改提交到 DOM 并运行布局效果，例如 useLayoutEffect。

  ¥Commit - After rendering components, React will submit the changes to the DOM and run layout effects, like useLayoutEffect.

• 剩余效果 - React 运行渲染子树的被动效果。这通常发生在绘制之后，此时 React 会运行类似 useEffect 的钩子。一个已知的例外是用户交互，例如点击或其他离散事件。在这种情况下，此阶段可以在绘制之前运行。

  ¥Remaining Effects - React runs passive effects of a rendered subtree. This usually happens after the paint, and this is when React runs hooks like useEffect. One known exception is user interactions, like clicks, or other discrete events. In this scenario, this phase could run before the paint.

了解更多关于渲染和提交的信息。

¥Learn more about renders and commits.

级联更新

¥Cascading updates

级联更新是性能回归的模式之一。如果在渲染过程中安排了更新，React 可以丢弃已完成的工作并启动新的渲染过程。

¥Cascading updates is one of the patterns for performance regressions. If an update was scheduled during a render pass, React could discard completed work and start a new pass.

在开发版本中，React 可以显示哪个组件安排了新的更新。这包括常规更新和级联更新。你可以通过点击 “级联更新” 条目来查看增强的堆栈跟踪，该条目还应显示安排更新的方法的名称。

¥In development builds, React can show you which Component scheduled a new update. This includes both general updates and cascading ones. You can see the enhanced stack trace by clicking on the “Cascading update” entry, which should also display the name of the method that scheduled an update.

了解更多关于副作用的信息。

¥Learn more about Effects.

组件

¥Components

组件轨道可视化了 React 组件的运行时间。它们以火焰图的形式显示，其中每个条目代表相应组件及其所有后代子组件的渲染时长。

¥The Components track visualizes the durations of React components. They are displayed as a flamegraph, where each entry represents the duration of the corresponding component render and all its descendant children components.

与渲染时长类似，effect 时长也以火焰图的形式表示，但颜色方案不同，与 Scheduler 轨道上的相应阶段保持一致。

¥Similar to render durations, effect durations are also represented as a flamegraph, but with a different color scheme that aligns with the corresponding phase on the Scheduler track.

在渲染和效果阶段可能会显示其他事件：

¥Additional events may be displayed during the render and effects phases:

• 挂载 - 已挂载相应的组件渲染或效果子树。

  ¥Mount - A corresponding subtree of component renders or effects was mounted.

• 卸载 - 已卸载相应的组件渲染或效果子树。

  ¥Unmount - A corresponding subtree of component renders or effects was unmounted.

• 重新连接 - 类似于 Mount，但仅限于使用 <Activity> 的情况。

  ¥Reconnect - Similar to Mount, but limited to cases when <Activity> is used.

• 断开连接 - 类似于 Unmount，但仅限于使用 <Activity> 的情况。

  ¥Disconnect - Similar to Unmount, but limited to cases when <Activity> is used.

更改的属性

¥Changed props

在开发版本中，当你点击组件渲染条目时，你可以检查属性中的潜在变化。你可以使用此信息来识别不必要的渲染。

¥In development builds, when you click on a component render entry, you can inspect potential changes in props. You can use this information to identify unnecessary renders.

服务器

¥Server

服务器请求

¥Server Requests

服务器请求轨道可视化了最终在 React 服务器组件中执行的所有 Promise。这包括任何 async 操作，例如调用 fetch 或异步 Node.js 文件操作。

¥The Server Requests track visualized all Promises that eventually end up in a React Server Component. This includes any async operations like calling fetch or async Node.js file operations.

React 会尝试将从第三方代码内部启动的 Promise 合并为一个 span，表示整个操作阻塞第一方代码的持续时间。例如，一个名为 getUser 的第三方库方法在内部多次调用 fetch，将被表示为一个名为 getUser 的 span，而不是显示多个 fetch span。

¥React will try to combine Promises that are started from inside third-party code into a single span representing the the duration of the entire operation blocking 1st party code. For example, a third party library method called getUser that calls fetch internally multiple times will be represented as a single span called getUser, instead of showing multiple fetch spans.

点击 span 将显示 Promise 创建位置的堆栈跟踪，以及 Promise 解析为的值的视图（如果有）。

¥Clicking on spans will show you a stack trace of where the Promise was created as well as a view of the value that the Promise resolved to, if available.

被拒绝的 Promise 会显示为红色，并带有其被拒绝的值。

¥Rejected Promises are displayed as red with their rejected value.

服务器组件

¥Server Components

服务器组件轨道可视化了它们等待的 React 服务器组件 Promise 的运行时间。时间以火焰图的形式显示，其中每个条目代表相应组件及其所有后代子组件的渲染时长。

¥The Server Components tracks visualize the durations of React Server Components Promises they awaited. Timings are displayed as a flamegraph, where each entry represents the duration of the corresponding component render and all its descendant children components.

如果你等待 Promise，React 将显示该 Promise 的持续时间。要查看所有 I/O 操作，请使用服务器请求轨道。

¥If you await a Promise, React will display duration of that Promise. To see all I/O operations, use the Server Requests track.

使用不同的颜色指示组件渲染的时长。颜色越深，持续时间越长。

¥Different colors are used to indicate the duration of the component render. The darker the color, the longer the duration.

服务器组件轨道组始终包含一个 “主要” 轨道。如果 React 能够并发渲染服务器组件，它将显示额外的 “并行” 轨道。如果同时渲染超过 8 个服务器组件，React 会将它们与最后一个 “并行” 轨道关联，而不是添加更多轨道。

¥The Server Components track group will always contain a “Primary” track. If React is able to render Server Components concurrently, it will display addititional “Parallel” tracks. If more than 8 Server Components are rendered concurrently, React will associate them with the last “Parallel” track instead of adding more tracks.