react-doctor

React Doctor

扫描 React 代码库，查找安全性、性能、正确性和架构方面的问题，并输出 0–100 的健康评分。

修改 React 代码后：

运行 npx react-doctor@latest --verbose --scope changed，并检查评分是否没有下降。

如果评分下降，请在提交前修复回归问题。

常规清理或改进代码：

运行 npx react-doctor@latest --verbose（默认使用 --scope full）扫描整个代码库。按严重程度修复问题——先处理错误，再处理警告。

针对 UI 设计进行专项审查：

运行 npx react-doctor@latest design --verbose。此命令仅选择带有 design 标签的 UI 组合、排版、交互、无障碍和动效规则，其中也包括在常规健康扫描中默认不启用的专项规则。

排查运行时性能问题：

在交互式终端中运行 npx react-doctor@latest scan <url> --format json。React Doctor 会打开一个隔离的系统 Chrome 配置文件，在用户重现缓慢交互时记录 DevTools 跟踪，并在 React 渲染时闪烁紫色轮廓并显示组件名称。按 Enter 后停止。先阅读结构化摘要，再检查返回的本地 .json.gz 跟踪文件，查找 CPU、浏览器和 React 组件相关证据。

如果用户需要使用已通过身份验证的浏览器状态，请使用 --cdp <remote-debugging-url>。这要求 Chrome 已在启用远程调试的情况下运行。切勿索要 Cookie 或复制用户的浏览器配置文件。将跟踪视为敏感的本地应用数据，未经明确许可，切勿上传。

/doctor — 完整的本地问题排查工作流

用户输入 /doctor、说“运行 react doctor”或要求进行完整的问题排查／清理（而非仅检查回归）时，请获取权威的本地排查操作手册，并遵循其中的每个步骤：

curl --fail --silent --show-error \
  --header 'Cache-Control: no-cache' \
  https://www.react.doctor/prompts/react-doctor-agent.md

该操作手册是唯一可信来源——它采用扫描 → 筛选 → 排查 → 修复 → 验证的循环，直接编辑工作树（绝不提交，也绝不创建 PR）。在源位置更新提示词后，所有 Agent 下次获取时都会使用更新后的内容——无需重新安装技能。

请将其与对应的逐规则提示词配合使用，地址为 https://www.react.doctor/prompts/rules/<plugin>/<rule>.md（在操作手册中按需获取），确保每项修复都采用权威且经过审查验证的方案。

如果团队希望检查其正在编辑的代码中已有的问题，请使用 --scope contextual --base origin/main。规则可以选择一个元素、函数、文件或一组明确相关的节点。对于 exhaustive-deps，修改 hook 调用或解析出的本地回调，可能会在未更改的依赖数组上触发问题提示。所有权范围不更广的规则仍会按更改行进行筛选。

配置或说明规则

如果用户想了解某条规则、不同意该规则，或想停用／调整要运行的规则（而非修复代码），请阅读 references/explain.md 并遵循其中的说明。先运行 npx react-doctor@latest rules explain <rule>，再通过 npx react-doctor@latest rules disable|set|category|ignore-tag … 应用范围最小的控制项；该命令会修改 doctor.config.*（或 package.json#reactDoctor）。

命令

npx react-doctor@latest --verbose --scope changed

标志	用途
.	扫描当前目录
--verbose	按规则显示受影响的文件和行号
--scope changed	仅报告相对于基础分支新增的问题（默认：全部）
--scope contextual	按各规则的选择，报告修改过的函数、JSX 元素或文件中的问题
--scope lines	仅报告修改行上的问题
--score	仅输出数值分数
design	仅运行针对 UI 设计的诊断

重用基础扫描结果

保存完整的 --json 扫描结果，然后传入 --baseline base-report.json，仅报告新增的问题。这也适用于 --scope changed。两次扫描须使用相同的版本和规则。问题按规则和文件路径分组，并跟踪 Git 重命名。仅报告各组数量增加的情况；数量未增加的组会跳过位置匹配。系统会根据指纹、消息相似度和经 Git 调整后的行距来选择新增问题。不会报告计数相同的格式调整和编辑。保存的报告必须使用相同的 textComponents、rawTextWrapperComponents 和 respectInlineDisables 设置。更改这些设置后，请重新生成基础报告，或使用 Git 比较。缺少指纹或 sourceFilterConfigHash 的旧报告必须重新生成。

GitLab 警告状态

对于 GitLab CI，--warning-exit-code 123 会在出现非阻断警告时返回 123。将其与 allow_failure: { exit_codes: 123 } 配合使用。错误仍会返回 1。接受范围为 2 到 255 的整数。--blocking warning 仍会返回 1。--blocking none 或 --score 会跳过此警告信号。