← EasyTool.me

React Doctor 完全指南：AI 编码 Agent 写的 React 太烂？一条命令扫出 0-100 分

Published: 2026-05-13 Reading: 8 min React / AI 编码 / 工具

2026 年 5 月 一个叫 React Doctor 的开源工具在 GitHub 上爆火 短短几天拿下 8.6K+ Stars GitHub Trending 首页

起因很简单 大家都发现了：AI 编码 Agent 写代码很快 但写出来的 React 代码质量一言难尽 状态管理混乱、性能问题、安全漏洞 甚至还有死代码 更麻烦的是 开发者已经不太读自己项目的代码了 根本不知道 Agent 写出了什么烂摊子

React Doctor 的出现刚好解决了这个问题——一条命令扫描你的整个 React 代码库 输出 0-100 的健康评分 附带可操作的问题清单

React Doctor 是什么？

React Doctor 由 millionco 团队开发 核心定位非常明确："Your agent writes bad React. This catches it."（你的 Agent 写得烂 React 这东西抓它）

它本质上是一个静态代码分析工具 但专为 React 生态深度定制 覆盖 6 大维度：

每个维度都有一套规则引擎 而且这些规则会根据你用的框架（Next.js / Vite / React Native）和 React 版本自动切换 不需要手动配置

五分钟上手：从扫描到修复

第一步：一键扫描

在项目根目录跑一条命令：

npx -y react-doctor@latest .

几秒钟后你会看到类似这样的输出：

React Doctor Report
━━━━━━━━━━━━━━━━━━━━
Overall Score: 62/100 (Needs work)

State & Effects    ████████░░  78/100
Performance        ██████░░░░  55/100
Architecture       ███████░░░  68/100
Security           █████████░  90/100
Accessibility      █████░░░░░  48/100
Dead Code          ████████░░  72/100

Top issues:
1. 12 components missing React.memo
2. 8 useEffect missing dependencies
3. 6 img tags missing alt attributes
4. 3 dangerouslySetInnerHTML usages

评分标准很简单：

第二步：教你的 Agent 不再犯同样错误

这是 React Doctor 最酷的功能——它不只是找到问题还能直接教你的 AI 编码 Agent 以后怎么写正确的代码：

npx -y react-doctor@latest install

这条命令会检测你项目中正在使用的 AI 编码 Agent 然后安装对应的规则配置 支持的 Agent 超过 50 个 包括：

安装后 你的 Agent 在生成新代码时就会自动遵循 React 最佳实践 告别 useEffect 滥用和数组索引当 key 的日子

如果想跳过交互式提示直接安装用 --yes：

npx -y react-doctor@latest install --yes

CI/CD 集成：在 PR 阶段自动把关

React Doctor 内置了一个 GitHub Actions 复合操作 可以在每次 Pull Request 时自动运行扫描 并在 PR 评论中报告结果：

# .github/workflows/react-doctor.yml
name: React Doctor

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  react-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: millionco/react-doctor@main
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

在 Pull Request 事件中 设置 github-token 后 扫描结果会自动发布（并持续更新）为 PR 评论 这样代码审查者一眼就能看到新代码的健康评分变化

没用 GitHub Actions？npx 形式同样有效：

npx -y react-doctor@latest --fail-on warning

设置 --fail-on warning 后 如果有任何 warning 级别以上的问题 CI 就会失败 防止低质量代码合入主分支

高级配置：按需定制规则

React Doctor 支持三级配置粒度 从最宽到最窄 覆盖不同场景：

项目根配置

在项目根目录创建 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"]
      }
    ]
  }
}

三级规则解释了这种配置方式的灵活性：

你也可以在 package.json 中用 "reactDoctor" 键配置 CLI 参数优先于配置文件

与现有 ESLint 配置集成

React Doctor 会自动检测项目中的 .eslintrc.json、.oxlintrc.json 配置 并将现有规则纳入评分 如果你不想合并现有 lint 配置 可以设置 adoptExistingLintConfig: false

它还支持两个可选插件 安装了会自动纳入同一扫描流程：

命令行参数速览

React Doctor 支持以下输入参数：

与其他工具的对比

React Doctor 最像"给 AI Agent 时代的 ESLint" 但它做了几件 ESLint 做不到的事：

与常规的 ESLint + Prettier 组合不同 React Doctor 不需要你记住配置规则 它的设计哲学是"你只要跑就行" 适合那些已经用 AI Agent 写代码 但不想花时间维护 lint 配置的团队

为什么这个工具很重要

2026 年 AI 编码 Agent 已经深度融入了日常开发流程 一个普遍的现象是：开发者正在越来越多地读代码而不是写代码 但读的代码有一半是 AI 写的 质量参差不齐

React Doctor 解决的正是这个矛盾：

它不只是一个 lint 工具 它是 AI 编码时代的代码审查自动化

在 AI 写代码成为常态的今天 工具需要从"帮人写更好的代码"进化为"帮 Agent 写更好的代码" React Doctor 就是这种思维转变的产物

上手建议

作为一个开源工具 react-doctor 完全免费 不需要注册 不需要配置 从 npx 开始 五分钟后你就能看到 AI Agent 到底把代码写成了什么样子

参考来源：