Back to Details

performance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diagnose React runtime performance

诊断React运行时性能

Measure one reproducible interaction, connect browser work to React renders, and report only conclusions supported by the trace.
针对可复现的交互进行测量，将浏览器工作与React渲染关联起来，仅报告有追踪记录支持的结论。

Define the interaction

定义交互

Before recording:
  1. Identify the target URL
  2. Write the exact actions to reproduce
  3. Choose the expected result
  4. Confirm whether authentication is required
Use a production build when available. Development builds add framework work that can distort render and script timings. If you must measure a development build, label that limitation in the report.
记录前：
  1. 确定目标URL
  2. 写下可复现问题的具体操作步骤
  3. 明确预期结果
  4. 确认是否需要身份验证
尽可能使用生产构建版本。开发构建版本会增加框架层面的额外工作，可能导致渲染和脚本计时失真。如果必须测量开发构建版本，请在报告中注明该限制。

Record the trace

记录追踪数据

Run the scan in an interactive terminal:
bash
npx react-doctor@latest scan http://localhost:3000 --format json
React Doctor opens an isolated Chrome profile. Perform the planned interaction while purple outlines identify rendered components. Press Enter after the interaction settles; recordings stop automatically after five minutes.
Interactive users can omit the URL and choose a detected localhost app or enter another URL. Agents must always pass the explicit URL so automated runs never wait for input.
For an authenticated session, connect through the Chrome DevTools Protocol (CDP):
bash
npx react-doctor@latest scan https://app.example.com \
  --cdp http://127.0.0.1:9222 \
  --format json
Use a dedicated debug profile for CDP because Chrome tracing is browser-wide. Sign in, close every non-blank tab, and then start the scan. React Doctor closes leftover blank tabs before tracing. Never request cookies, copy a browser profile, or close an externally managed browser.
The compressed 
.json.gz
trace can contain URLs, source paths, and application behavior. Keep it local unless an upload is explicitly approved.
在交互式终端中运行扫描命令：
bash
npx react-doctor@latest scan http://localhost:3000 --format json
React Doctor会打开一个独立的Chrome配置文件。在执行预设交互的过程中，紫色轮廓会标记出正在渲染的组件。交互稳定后按Enter键结束记录；记录会在五分钟后自动停止。
交互式用户可以省略URL，选择检测到的本地应用或输入其他URL。Agent必须始终传入明确的URL，以确保自动化运行不会等待输入。
如需在已登录会话中进行扫描，请通过Chrome DevTools Protocol (CDP)连接：
bash
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、源码路径和应用行为数据。除非明确批准上传，否则请将文件保存在本地。

Read the report

解读报告

Evaluate the report in this order:
  1. Capture support: confirm React detection, build type, React tracks, and Long Animation Frame support
  2. User impact: inspect the worst interaction, total blocking duration, Largest Contentful Paint (LCP), and Cumulative Layout Shift (CLS)
  3. Browser work: inspect long frames and script hotspots for event handling, JavaScript, style, layout, and paint cost
  4. React work: inspect component render count, total self time, and maximum self time
  5. Capture limits: read every warning, especially dropped event counts
Follow these interpretation rules:
  • A high render count is evidence, not a defect. Pair it with duration and user impact
  • Generated chunk names identify browser work, not the owning source component
  • A slow interaction can be browser-bound even when every component render is cheap
  • Repeated Event Timing records with one interaction identifier represent one interaction
  • Dropped component events make hotspot totals incomplete
  • Use purple labels to identify the active subtree, then use recorded timings to set severity
按以下顺序评估报告：
  1. 捕获支持情况：确认是否检测到React、构建类型、React追踪记录以及Long Animation Frames支持情况
  2. 用户影响：查看性能最差的交互、总阻塞时长、Largest Contentful Paint (LCP)和Cumulative Layout Shift (CLS)指标
  3. 浏览器工作负载：检查长帧和脚本热点，包括事件处理、JavaScript执行、样式计算、布局和绘制的开销
  4. React工作负载：检查组件渲染次数、总自执行时间和最大自执行时间
  5. 捕获限制：查看所有警告信息，尤其是丢失的事件数量
遵循以下解读规则：
  • 高渲染次数是一种证据，而非缺陷。需结合时长和用户影响来分析
  • 生成的代码块名称用于标识浏览器的工作负载，而非所属的源码组件
  • 即使每个组件的渲染成本都很低，交互缓慢也可能是由浏览器层面的问题导致的
  • 带有同一交互标识符的重复Event Timing记录代表同一次交互
  • 丢失的组件事件会导致热点统计数据不完整
  • 使用紫色标签识别活跃子树，再根据记录的时长确定问题严重程度

Connect measurements to source

将测量结果关联到源码

Search the repository for measured component display names and event handlers. Confirm that each candidate runs in the recorded flow before reporting it.
Open the DevTools trace when the summary cannot explain a long frame. Correlate the interaction timestamp with script tasks, style or layout work, React tracks, and paint. Do not infer causality from neighboring timestamps alone.
在代码仓库中搜索被测组件的显示名称和事件处理函数。在报告前，确认每个候选对象确实在记录的交互流程中执行过。
当摘要无法解释长帧问题时，打开DevTools追踪记录。将交互时间戳与脚本任务、样式或布局工作、React追踪记录以及绘制操作关联起来。切勿仅根据相邻时间戳推断因果关系。

Report findings

报告发现

Use this structure:
markdown
undefined
使用以下结构：
markdown
undefined

Flow tested

Flow tested

tested_url, build_type, and exact_interaction
tested_url, build_type, and exact_interaction

Verdict

Verdict

one_evidence_backed_paragraph
one_evidence_backed_paragraph

Evidence

Evidence

SignalMeasurementInterpretation
Worst interactionduration_msmeasured_cause
Total blockingduration_msmeasured_scope
Top componentrender_count and duration_msmeasured_impact
SignalMeasurementInterpretation
Worst interactionduration_msmeasured_cause
Total blockingduration_msmeasured_scope
Top componentrender_count and duration_msmeasured_impact

Findings

Findings

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

Limits

Limits

capture_warnings, missing_support, or environmental_caveats

Do not pad the report with static lint findings. Include source findings only when runtime evidence connects them to the tested flow.
capture_warnings, missing_support, or environmental_caveats

请勿在报告中添加静态代码检查的结果。只有当运行时证据表明源码问题与被测流程相关时，才将其纳入报告。

Validate a fix

验证修复效果

Do not edit code unless code changes are requested. After a fix:
  1. Rebuild with the same mode
  2. Record the same interaction at the same viewport
  3. Run three before and three after samples when timing variance could change the conclusion
  4. Compare medians for interaction, blocking, and component duration
  5. Confirm behavior and accessibility did not regress
Reject improvements that only move work outside the recorded window or disable useful behavior.
除非要求修改代码，否则请勿编辑代码。修复完成后：
  1. 使用相同的构建模式重新构建项目
  2. 在相同视口下记录同一次交互
  3. 若时间差异可能影响结论，请分别采集三次修复前和修复后的样本
  4. 对比交互时长、阻塞时长和组件执行时长的中位数
  5. 确认功能和无障碍访问性未出现退化
拒绝那些仅将工作负载转移到记录窗口之外，或禁用了有用功能的“优化”。