React Doctor 是什么？React 代码质量诊断工具介绍

React Doctor 是什么？React 代码质量诊断工具介绍

一个 React 项目能正常跑起来，可不代表它的代码状态够健康。组件里说不定藏着多余的 useEffect、会放大重渲染的写法、越攒越乱的 prop drilling，还可能有无障碍、安全或是依赖方面的风险。React Doctor 干的事儿特别直白：你在项目根目录跑一次扫描，它就能把这些问题定位到具体文件和行号，再给出一份 0–100 的代码健康分。

它不是“另一个 ESLint 皮肤”

React Doctor 是专门面向 React 代码库的确定性诊断工具。官方把它的检查范围分成了五大类：状态与副作用、性能、架构、安全和无障碍；当前版本还会搭配死代码分析与依赖供应链检查一起做。它会先识别你项目用的框架、React 版本和语言环境，再启用对应匹配的规则。

它和普通 lint 工具的核心区别，可不是「报错数量更多」，而是把 React 常见反模式、项目范围分析和健康分都整合到了同一个工作流里。举个例子，像把 props 复制进 state 再用 effect 同步、effect 没写清理逻辑、列表 key 用了不稳定的值、组件职责太杂这类问题，可比「这里少了一个分号」的检查，更贴近项目真实的维护成本。

它也不会让团队推翻现有的规则体系。官方文档说得很清楚，React Doctor 是对现有 lint 流程的补充，还能直接复用已有的 JSON 格式 ESLint 或 oxlint 配置。要是想把诊断功能整合到原来的 lint 命令里，也有对应的插件可以用。

第一次扫描项目，先跑这两条命令

进到你的 React 项目根目录，先跑一次全量检查：

npx react-doctor@latest

改bug的时候不用总盯着所有历史问题不放，只想看当前分支新增的诊断项，就换这条命令：

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

终端跑出来的结果会直接给出健康分、错误和警告的数量，还会标清楚对应的文件、行号、触发规则以及修复建议。优先处理严重级别高的安全和性能问题就行；要是看不懂某条诊断，用 why 查询指定位置的原因，比直接关掉规则要稳妥得多：

npx react-doctor@latest why src/App.tsx:42

健康分应该怎么用

这个0–100分的健康分最适合用来观察趋势：同一次提交能得到可复现的结果，团队就能明确判断一次重构下来，代码库到底是变好了还是变差了。要注意的是，分数不等于「应用正确率」，也代替不了 TypeScript、单元测试、端到端测试、React Profiler 或是人工代码评审的作用。

更顺手的排查顺序是先盯 error 类问题，再处理 security 和 performance 相关项，之后再搞定 bugs、accessibility 还有 maintainability 这几类。要是碰到业务上确实合理的例外情况，优先做文件级或者规则级的小范围配置，千万别为了凑 100 分直接把整类检查都关了。

配置规则，不必迁就默认值

React Doctor 支持 doctor.config.ts、doctor.config.json 这类配置文件，也能读取 package.json 里的 reactDoctor 字段。大家平时常调的配置主要有这几项：排除生成文件、修改某条规则的严重级别、选择扫描范围，以及决定 error 或 warning 是否阻断流程。

举个实际场景：仓库里如果有自动生成的接口代码，直接忽略对应目录就行；要是某个组件确实得用 dangerouslySetInnerHTML，也能单独给这个文件开局部例外。官方还提供了 rules list、rules explain、rules set 和 rules disable 这类命令，改规则前先查清楚规则命中的原因就好。

接入代码代理和 CI，才是它更有价值的场景

跑一下 npx react-doctor@latest install 命令，就能给 Codex、Claude Code、Cursor、OpenCode 这类代码代理装上对应的技能，让代理做完 React 代码改动后自动扫描。这个工具刚好能给 AI 生成的代码加一道确定性检查关：模型负责改代码，规则负责揪出新问题，代理再照着诊断结果返工。

团队仓库可以运行 npx react-doctor@latest ci install。该命令会生成 GitHub Actions 工作流或 GitLab CI 脚手架。GitHub Action 能在 PR 中汇总新诊断、添加行内评论和提交状态；默认门禁为提示模式，需要团队根据现状把 blocking 调成 error 或 warning，避免刚接入就被旧问题卡住。

使用前需要知道的三个边界

• 分数不是质量证明。静态规则看不到所有运行时交互、接口语义和产品逻辑，低风险分支仍要跑测试和人工评审。

• 规则需要结合项目校准。误报或业务例外无法完全避免，先用 why 查原因，再做最窄范围的忽略。

• 注意网络检查与遥测。依赖供应链检查会使用 Socket.dev；官方仓库说明 CLI 会发送崩溃、运行环境、项目形态和触发规则名称/数量等遥测，但不发送文件内容或具体诊断。敏感环境可以使用 --no-telemetry，也可按配置关闭供应链检查。

一张检查清单，判断它是否适合你的项目

• 项目使用 React、Next.js、Vite、TanStack、React Native、Expo 或 Preact。

• 团队想把 effect、性能、架构、安全和无障碍问题集中到一份报告里。

• AI 代码产量增加，需要一套可重复运行、能定位到行的质量护栏。

• 愿意先校准规则，再逐步把增量扫描放进 PR，而不是只追一个漂亮分数。

只要中了两三项，就值得你在真实分支上跑一遍 React Doctor 了。记得先存好第一次的检测结果，再去处理报错和新引入的问题；等误报、例外情况都收敛得差不多了再接入 CI，这样健康分才不会只是一次性的「体检数字」，而是能变成团队长期跟进的工程信号。