GenericAgent 是什么？自进化 AI Agent 框架介绍
2026-07-18 3408430
2026-07-18 0
React Doctor 是什么？React 代码质量诊断工具介绍
一个 React 项目能正常跑起来，可不代表它的代码状态够健康。组件里说不定藏着多余的 useEffect、会放大重渲染的写法、越攒越乱的 prop drilling，还可能有无障碍、安全或是依赖方面的风险。React Doctor 干的事儿特别直白：你在项目根目录跑一次扫描，它就能把这些问题定位到具体文件和行号，再给出一份 0–100 的代码健康分。
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
--scope changed：它会把扫描范围收窄到当前分支新引入的问题上。旧的 --diff 参数还能用，但官方 CLI 文档已经把它标成弃用别名了。来源：React Doctor 官方 Quickstart，2026-07-17 截图。终端跑出来的结果会直接给出健康分、错误和警告的数量，还会标清楚对应的文件、行号、触发规则以及修复建议。优先处理严重级别高的安全和性能问题就行；要是看不懂某条诊断，用 why 查询指定位置的原因，比直接关掉规则要稳妥得多：
npx react-doctor@latest why src/App.tsx:42
这个0–100分的健康分最适合用来观察趋势：同一次提交能得到可复现的结果，团队就能明确判断一次重构下来，代码库到底是变好了还是变差了。要注意的是，分数不等于「应用正确率」，也代替不了 TypeScript、单元测试、端到端测试、React Profiler 或是人工代码评审的作用。
更顺手的排查顺序是先盯 error 类问题，再处理 security 和 performance 相关项，之后再搞定 bugs、accessibility 还有 maintainability 这几类。要是碰到业务上确实合理的例外情况，优先做文件级或者规则级的小范围配置，千万别为了凑 100 分直接把整类检查都关了。
blocking 决定什么级别会让工作流失败，scope 决定 PR 中检查哪些问题。来源：React Doctor 官方文档，2026-07-17 截图。React Doctor 支持 doctor.config.ts、doctor.config.json 这类配置文件，也能读取 package.json 里的 reactDoctor 字段。大家平时常调的配置主要有这几项：排除生成文件、修改某条规则的严重级别、选择扫描范围，以及决定 error 或 warning 是否阻断流程。
举个实际场景：仓库里如果有自动生成的接口代码，直接忽略对应目录就行；要是某个组件确实得用 dangerouslySetInnerHTML，也能单独给这个文件开局部例外。官方还提供了 rules list、rules explain、rules set 和 rules disable 这类命令，改规则前先查清楚规则命中的原因就好。
跑一下 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，这样健康分才不会只是一次性的「体检数字」，而是能变成团队长期跟进的工程信号。