React Doctor 深度技术解析：给 AI 写的 React 代码做体检
一、项目概述
React Doctor 是由 million（虚拟 DOM 优化库团队）开发的 React 代码健康度扫描工具。一条命令扫描整个代码库，输出 0-100 的健康评分和可操作诊断。它专为 AI 编码 agent 时代设计——当 agent 写了糟糕的 React 代码，React Doctor 能帮你抓住它。
核心特性：
二、技术原理
2.1 扫描架构
┌─────────────────────────────────────────┐
│ CLI / GitHub Action │
│ 扫描入口，输出评分和诊断报告 │
├─────────────────────────────────────────┤
│ Rule Engine │
│ 状态/副作用 · 性能 · 架构 · 安全 · a11y │
│ 规则自动根据框架和 React 版本切换 │
├─────────────────────────────────────────┤
│ AST Analyzer │
│ 解析 JSX/TSX，提取组件树和数据流 │
├─────────────────────────────────────────┤
│ Lint Integration │
│ 合并 oxlint/eslint 规则，计入评分 │
└─────────────────────────────────────────┘
2.2 多维度诊断规则
React Doctor 覆盖六大诊断维度：
| 维度 | 检测内容 | |------|----------| | 状态与副作用 | 不必要的 useEffect、派生状态、链式状态更新、事件监听器泄漏 | | 性能 | 不必要的重渲染、缺失的 memo/useMemo、数组索引作为 key | | 架构 | 组件过度拆分、props drilling、缺少错误边界 | | 安全 | dangerouslySetInnerHTML 滥用、未验证的输入 | | 可访问性 | 缺失 alt 标签、自动焦点、ARIA 属性错误 | | 死代码 | 未使用的导入、未使用的组件、不可达代码 |
2.3 与现有 Lint 工具集成
React Doctor 能自动检测并合并项目中的 .oxlintrc.json 或 .eslintrc.json 配置。如果安装了以下可选插件，规则会自动折叠进扫描：
| 插件 | 添加的规则 | 命名空间 |
|------|-----------|----------|
| eslint-plugin-react-hooks v6/v7 | React Compiler 正确性规则 | react-hooks-js/* |
| eslint-plugin-react-you-might-not-need-an-effect v0.10+ | 副作用反模式规则 | react-ymnnane/* |
2.4 Agent 集成机制
通过 npx -y react-doctor@latest install 命令，React Doctor 能自动检测项目中的编码 agent 配置文件（如 .cursorrules、CLAUDE.md、AGENTS.md 等），并注入 React 最佳实践规则。这意味着 agent 在写代码前就能"知道"正确的方式。
2.5 GitHub Actions 集成
name: React Doctor
on:pull_request:push:branches: [main]
permissions:contents: readpull-requests: write
jobs:react-doctor:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v5with:fetch-depth: 0- uses: millionco/react-doctor@mainwith:diff: maingithub-token: ${{ secrets.GITHUB_TOKEN }}
PR 评论自动更新，评分通过 score output 暴露，可在后续步骤中使用。
三、安装与快速开始
3.1 环境要求
3.2 安装与运行
npx -y react-doctor@latest .
立即获得评分和诊断报告。无需安装，一条命令搞定。
3.3 为编码 Agent 安装
npx -y react-doctor@latest install
自动检测项目中的 agent 并注入最佳实践配置。
3.4 配置
在项目根目录创建 react-doctor.config.json：
{"ignore": {"rules": ["react/no-danger", "jsx-a11y/no-autofocus"],"files": ["src/generated/**"],"overrides": [{"files": ["components/modules/diff/**"],"rules": ["react-doctor/no-array-index-as-key"]}]}
}
三层忽略粒度：
ignore.rules：全局静默某规则ignore.files：对匹配文件静默所有规则ignore.overrides：对匹配文件静默指定规则（推荐）四、使用方法与实战
4.1 本地开发扫描
npx -y react-doctor@latest .
扫描当前目录，输出评分和问题列表。
4.2 差异扫描（CI 常用）
npx -y react-doctor@latest --diff main
只报告相对于 main 分支新增的问题，适合 CI 门禁。
4.3 失败阈值控制
npx -y react-doctor@latest --fail-on warning
将 CI 失败阈值设为 warning 级别（默认是 error）。
4.4 Monorepo 支持
npx -y react-doctor@latest apps/web
指定子目录扫描，适合 monorepo 架构。
五、常见问题与解决方案
5.1 评分偏低
检查报告中的 Critical 级别问题优先修复。常见扣分项：
5.2 误报处理
使用 react-doctor.config.json 的 ignore.overrides 精确忽略特定文件的特定规则。
5.3 扫描速度慢
大型项目可使用 --diff 选项只扫描变更部分。也可配置 ignore.files 排除生成代码目录。
5.4 与 ESLint 冲突
React Doctor 会自动合并现有的 ESLint/oxlint 配置。如需禁用此行为，设置 adoptExistingLintConfig: false。
六、总结
React Doctor 填补了 React 代码质量扫描工具的一个重要空白——它不只是另一个 linter，而是面向 AI 编码 agent 时代设计的"代码体检"工具。0-100 健康评分、六大维度诊断、自动规则适配、CI/CD 集成、以及 50+ agent 的最佳实践注入，让 React Doctor 成为现代 React 开发者的必备工具。
GitHub 地址： https://github.com/millionco/react-doctor
稳定可靠低价的AI中转站：X API