你的 AI 写的 React 烂透了？这个 8000+ Star 的开源工具能揪出 90% 的「Agent 屎山」

Vibe Coding 火了大半年了，我身边的同事基本人手一个 AI 编码代理——Claude Code、Cursor、Codex，每天吭哧吭哧地让 Agent 写业务代码。

效率是真的高。但问题也是真的多。

上周我 review 同事用 Claude Code 生成的一个 PR，里面有一个 useEffect，依赖数组是空的，里面却用一个闭包变量更新 state。也就是说这段代码会在组件挂载时跑一次，之后就再也不会响应数据变化了。编译不报错，TypeScript 不报错，ESLint 也没配这条规则——它就这么安安静静地躺进了 main 分支。

说实话，这种事情我自己也经常干。AI 写的 React 代码，能用，但经不起细看。状态管理混乱、不必要的 re-render、闭包陷阱、内存泄漏、可访问性一塌糊涂……这些问题 AI 代理不会主动告诉你，等你发现的时候往往已经上线了。

所以我看到 react-doctor 的时候，第一反应就是：终于有人做这个了。

它是什么？

一句话概括：react-doctor 是一个 React 代码健康度扫描工具，专治 AI 写的烂 React。

它的 Github README 第一条就是：

Your agent writes bad React. This catches it.

直白，粗暴，我喜欢的风格。

它的工作方式也很简单——在你项目根目录下跑一条命令：

npx -y react-doctor@latest .

然后它会扫描你的整个代码库，给你打出一个 0 到 100 的健康分，并列出所有问题的清单。

75+ 分：Great — 代码质量良好
50-74 分：Needs work — 需要改进
50 分以下：Critical — 你最好立刻修一下

这个评分体系有点像 Lighthouse，对前端同学来说非常直观。

截至今天（2026 年 5 月），react-doctor 在 GitHub 上已经有 8,000+ stars，日增 200+ stars，势头很猛。背后的团队是 millionco，也就是造了 Million.js 和 React Compiler 的那个团队。他们做 React 性能优化起家，对「烂 React」的理解是有工业级深度的。

快速上手

安装零配置，直接在项目里跑：

npx -y react-doctor@latest .

支持 Next.js、Vite、React Native。自动识别你的框架类型和 React 版本，规则集也会根据环境自动开关。如果你是 Next.js 项目，它会启用 SSR 相关的检查规则；如果是 React Native，会有移动端专项的规则。

在我自己的一个 Next.js 项目中首次跑的结果：得分 62，Needs work。列出来了 40+ 个问题，涵盖状态管理、性能、安全性、可访问性、死代码五个维度。说实话比我预期的要差，但比我担心的要好。

核心功能拆解

react-doctor 的检查覆盖六大维度：

1. State & Effects（状态和副作用）

这是 AI 最容易翻车的区域。它检查的典型问题包括：

级联 setState：在一个 useEffect 里连续 set 两个 state，每次 set 都会触发一次 re-render
派生 state：用一个 state 来存另一个 state 的计算结果，纯粹浪费 re-render
在 render 里调用 setState：直接导致无限循环
闭包陷阱：useEffect 依赖不完全导致 stale closure

举个例子，AI 经常写的这种代码就会被标记：

// ❌ react-doctor: no-derived-useState
const [items, setItems] = useState(data);
const [filtered, setFiltered] = useState([]);

useEffect(() => {
  setFiltered(items.filter(i => i.active));
}, [items]);

改成一个 useMemo 就能省掉一次额外的 re-render：

// ✅
const [items, setItems] = useState(data);
const filtered = useMemo(() => items.filter(i => i.active), [items]);

2. Performance（性能）

这一块检查不必要的 re-render、可优化的 useMemo/useCallback 使用、大列表渲染等。

有意思的是，它不仅检查你哪里没加 useMemo，也会检查你哪里不该加。因为盲目 useMemo 也是有开销的，react-doctor 的规则是比较审慎的。

3. Architecture（架构）

组件拆分不合理、Props drilling 过深、职责不清的巨型组件——这些都是 AI 生成代码的重灾区。Agent 倾向于「能用就行」，对可维护性基本不操心。

4. Security（安全）

XSS 风险、dangerouslySetInnerHTML 使用不当等。AI 经常会为了省事直接 dangerouslySetInnerHTML，react-doctor 会把这些地方高亮出来。

5. Accessibility（可访问性）

缺少 aria-label、不合适的 role 属性、autofocus 滥用等。这一项默认权重不高，但如果你在意 a11y，可以调高。

6. Dead Code（死代码）

从未被使用的组件、导出，或者永远为 false 的条件分支。AI 生成代码的时候经常留下这些「代码残骸」。

每个诊断都附带文件名、行号和修复建议，不是光告诉你「这里有问题」就完了，而是告诉你为什么有问题、怎么改。

配合 CI/CD，拦住烂代码

扫描一次发现问题当然好，但如果能在每次 PR 时就自动检查，那就更香了。react-doctor 提供了 GitHub Actions 集成：

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 }}

配置好之后，每次提 PR，它就会自动扫描变更的文件（不是全量扫描），把发现的 React 问题直接评论到 PR 里。你还可以设置 fail-on: warning，让 CI 在出现 warning 级别的问题时直接报红——烂代码连门都进不来。

不用 GitHub Actions 也没关系，简单的 npx 命令一样可以在任何 CI 里跑：

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

和 AI Agent 配合：从「治病」到「防病」

这个功能我觉得是最酷的——react-doctor 不只是个「事后扫描」工具，它可以直接安装到你的 AI 编码代理里，让 Agent 从一开始就知道怎么写好的 React。

npx -y react-doctor@latest install

运行后会检测你本机安装的 AI 代理（Claude Code、Cursor、Codex、OpenCode 等 50+ 个），然后询问你要装到哪个。加 --yes 可以跳过交互。

安装之后，react-doctor 会作为 Agent Skills 注入到代理的工作流中。当 Agent 生成 React 代码时，它会按照 react-doctor 定义的规则来——相当于给 AI 配了个 React 最佳实践的「教练」。

我装到 Claude Code 之后，生成出来的 React 代码质量确实有明显提升。至少 useEffect 的依赖数组不再乱写了，也不会在 render 里直接 setState。感觉像是在 AI 脑子里装了道「质量门禁」。

配置灵活，按需调整

不是每一条规则都适用于你的项目。react-doctor 的配置体系设计得很实用：

{
  "ignore": {
    "rules": ["react/no-danger"],
    "files": ["src/generated/**"],
    "overrides": [
      {
        "files": ["components/modules/diff/**"],
        "rules": ["react-doctor/no-array-index-as-key"]
      }
    ]
  }
}

三个层级，从粗到细：

ignore.rules：全局禁用某条规则
ignore.files：对整个目录/文件禁用所有规则（慎用）
ignore.overrides：对特定文件只禁用特定几条规则（推荐）

也可以集成你现有的 ESLint 配置（.eslintrc.json 或 .oxlintrc.json），react-doctor 会自动合并其中的规则到评分体系中。

代码级别的忽略也支持：

// react-doctor-disable-next-line react-doctor/no-cascading-set-state
useEffect(() => {
  setA(value);
  setB(value);
}, [value]);

这些设计和 ESLint 的生态非常一致，上手门槛几乎为零。

竞品对比

说到 React 代码质量工具，ESLint + eslint-plugin-react-hooks 是最常见的组合。但它们有两个核心问题：

ESLint 不会给你打健康分。几十个警告你不知道哪些是真正严重的
eslint-plugin-react-hooks 只覆盖 hooks 规则，对性能、架构、可访问性、死代码完全不管

Biome/Oxlint 的 React 规则覆盖更全一些，但它们本质上是 Linter，不是 Doctor。Linter 告诉你语法/模式哪里不对，Doctor 告诉你代码健不健康。这是两种不同的心智模型。

react-doctor 的价值不在于多查了几条规则，而在于它把「React 代码质量」这件事量化了。你说「我们的 React 代码质量还行」——证据呢？跑一次 react-doctor，75 分就是还行，45 分就是不行。这种量化的对话方式在团队协作中非常有用，尤其是要说服老板/PM 拨时间做代码质量改进的时候。

而且 react-doctor 会自动合并你已有的 ESLint/Oxlint 配置，不用废弃现有的 Lint 流程，直接在它上面加一层健康度评估。

使用感受

用了大概一周，说几个真实的感受：

好的方面：

零配置起步真的爽。一行 npx 就能跑，不用折腾半天配规则
诊断信息很清晰，每个问题都有具体的文件、行号和修改建议，不是那种「自己悟吧」的风格
Agent Skills 模式是真正的差异化功能。让 AI 知道怎么写好 React，比事后检查更高明
CI 集成很顺手，PR 评论的形式让团队 review 聚焦在代码逻辑而不是代码质量问题
框架检测准确。我的 Next.js 项目它自动识别出来了，启用了 SSR 相关规则

不太满意的：

首次扫描速度不算快。我的中型项目（300+ 组件）大概跑了 30 多秒。虽然比跑一次完整 TypeScript check 快，但还是希望后续版本能优化
部分规则的误报率偏高。比如「不必要的 useMemo」这条，在复杂类型推导的场景下会误判
可访问性这块的检查比较基础，如果你有严谨的 a11y 需求，还得配合 axe-core 之类的专业工具

推荐指数：⭐⭐⭐⭐（4.5/5）

减掉 0.5 分主要是速度和误报率，对于刚发布不久的 v1.x 来说完全可以接受。

适合人群

重度 AI 编码用户（Claude Code/Cursor/Codex 日常使用）：基本上是必装工具，Agent Skills 模式能帮你减少很多 review 负担
React 项目 Tech Lead：CI 集成的「PR 质量门禁」非常好用，能把代码质量规范落到实处
正在做 React 项目的团队：量化代码质量的工具很稀缺，react-doctor 的健康评分在团队沟通中价值很大
初学者/转 React 的开发者：每条诊断附带的修复建议非常友好，相当于一个随时可用的「React 最佳实践导师」

不太适合

项目本身已经配了很完善的 ESLint + Biome + axe-core 组合，且团队代码规范执行很严格——这时的边际收益会小一些

react-doctor 解决了一个 AI 编码时代的真实痛点：Agent 能写 React，但写不好 React。它不像传统 Linter 那样只是列出一条条规则违规，而是给出了一个更接近「代码 review 感受」的体验——给整体打健康分，告诉你哪块最薄弱，还建议你怎么改。

目前 8,059 stars、MIT 协议，项目地址：

👉 github.com/millionco/r…

如果你的项目已经在用 AI 代理写 React，强烈建议跑一遍。你会发现一座「屎山」，但至少你知道它有多高了。