performance

诊断 React 运行时性能

测量一次可复现的交互，将浏览器工作与 React 渲染关联起来，并且只报告有追踪记录支持的结论。

定义交互

开始录制前：

1. 确定目标 URL
2. 写下重现交互的确切操作
3. 选择预期结果
4. 确认是否需要身份验证

如果有生产构建，请使用生产构建。开发构建会增加框架工作，从而扭曲渲染和脚本计时。如果必须测量开发构建，请在报告中注明这一限制。

录制追踪

在交互式终端中运行扫描：

npx react-doctor@latest scan http://localhost:3000 --format json

React Doctor 会打开一个隔离的 Chrome 配置文件。按照计划执行交互，紫色轮廓会标示已渲染的组件。交互稳定后按 Enter；录制会在五分钟后自动停止。

交互式用户可以省略 URL，然后选择检测到的本地应用，或输入其他 URL。Agent 必须始终传入明确的 URL，这样自动运行就不会等待输入。

对于已通过身份验证的会话，请通过 Chrome DevTools Protocol（CDP）连接：

npx react-doctor@latest scan https://app.example.com \
  --cdp http://127.0.0.1:9222 \
  --format json

请为 CDP 使用专用调试配置文件，因为 Chrome 追踪会影响整个浏览器。登录后关闭所有非空白标签页，然后开始扫描。React Doctor 会在追踪前关闭遗留的空白标签页。切勿请求 Cookie、复制浏览器配置文件或关闭由外部管理的浏览器。

压缩后的 .json.gz 追踪文件可能包含 URL、源文件路径和应用行为。除非明确批准上传，否则请将其保留在本地。

阅读报告

按以下顺序评估报告：

1. 采集支持情况：确认 React 检测、构建类型、React 轨道和 Long Animation Frame 支持情况
2. 用户影响：检查最差交互、总阻塞时长、最大内容绘制（LCP）和累计布局偏移（CLS）
3. 浏览器工作：检查长帧和脚本热点中的事件处理、JavaScript、样式、布局和绘制耗时
4. React 工作：检查组件渲染次数、总自身耗时和最大自身耗时
5. 采集限制：阅读所有警告，尤其是丢弃的事件数量

遵循以下解读规则：

• 渲染次数多是证据，不代表存在缺陷。应结合耗时和用户影响进行判断
• 生成的代码块名称标识的是浏览器工作，而不是所属的源组件
• 即使每个组件的渲染耗时都很短，交互也可能受浏览器工作限制
• 具有同一交互标识符的重复 Event Timing 记录代表一次交互
• 丢弃的组件事件会导致热点总耗时不完整
• 使用紫色标签识别活动子树，再依据记录的计时确定严重程度

将测量结果与源代码关联

在代码库中搜索测得的组件显示名称和事件处理程序。报告候选项前，确认它们确实会在记录的流程中运行。

如果摘要无法解释长帧，请打开 DevTools 追踪记录。将交互时间戳与脚本任务、样式或布局工作、React 轨道和绘制相关联。不要仅根据相邻的时间戳推断因果关系。

报告发现

使用以下结构：

## Flow tested

tested_url, build_type, and exact_interaction

## Verdict

one_evidence_backed_paragraph

## Evidence

| Signal            |                  Measurement | Interpretation  |
| ----------------- | ---------------------------: | --------------- |
| Worst interaction |                  duration_ms | measured_cause  |
| Total blocking    |                  duration_ms | measured_scope  |
| Top component     | render_count and duration_ms | measured_impact |

## Findings

1. `path/to/component.tsx:42`: measured_problem, evidence, and smallest_fix

## Limits

capture_warnings, missing_support, or environmental_caveats

不要在报告中凑入静态 lint 检查发现的问题。只有运行时证据表明源代码问题与所测流程有关时，才将其纳入报告。

验证修复

除非用户要求修改代码，否则不要编辑代码。修复后：

1. 使用相同模式重新构建
2. 在相同视口下录制相同交互
3. 如果计时波动可能影响结论，则修复前和修复后各录制三次
4. 比较交互、阻塞和组件耗时的中位数
5. 确认行为和无障碍性没有退化

如果某项改进只是将工作移出录制时间范围，或禁用了有用功能，则应予以否决。