React Doctor：AI 编程时代的 React 代码守门员

当 AI 写出带病的 React 代码

2025 年，AI 编程工具已经走进了每一个开发团队的日常工作。Claude Code、Cursor、Codex 等工具能在几秒钟内生成一个功能模块，能在几分钟内搭建起一套 CRUD 页面。然而，当这些 AI 生成的 React 代码被部署到生产环境后，开发者们开始陆续发现一些奇怪的 bug：状态更新没有同步到 UI、异步请求没有正确清理副作用、列表渲染缺少唯一的 key 属性、性能在大量数据下急剧下降。

这些问题并非罕见，而是 AI 生成代码的共性缺陷。AI 擅长生成「看起来正确」的代码，但往往忽略了 React 的运行机制和最佳实践。React Doctor 正是为此而生——它是一个专门针对 React 代码的静态分析工具，像一名耐心的「代码医生」一样，扫描你的代码库，找出 AI 或人类开发者容易犯的错误。

项目背景：Million 公司的 AI 质量管控实践

React Doctor 由 Million 公司开发维护。Million 是一家专注于 React 性能优化的科技公司，其同名旗舰产品 million.js 是一个被广泛使用的 React 虚拟 DOM 替代方案，在 GitHub 上拥有超过 3.3 万颗星。

Million 团队在日常开发中发现，AI 编程工具虽然极大提升了开发效率，但生成的 React 代码质量参差不齐，尤其在以下五个维度上问题突出：

• State & Effects（状态与副作用）：useEffect 依赖遗漏、状态更新时机错误
• Performance（性能）：不必要的重新渲染、低效的列表操作
• Architecture（架构）：组件职责混乱、代码组织不合理
• Security（安全）：XSS 风险、不安全的直接 DOM 操作
• Accessibility（无障碍）：缺少 ARIA 属性、键盘导航支持

项目核心设计理念是：规则优先于 AI，通过确定性规则扫描，而非模糊的代码风格建议来保证代码质量。

核心功能：五维扫描 + 多框架兼容

React Doctor 的分析能力覆盖了 React 开发的五大高频问题领域，每一类问题都有对应的检测规则，规则库持续维护更新。

状态与副作用检测

这是 React 开发中最容易出问题的区域。常见错误包括：useEffect 中没有正确声明依赖项（导致闭包陷阱）、在 useEffect 中直接修改 state（违反 React 单向数据流）、在 unmount 组件后继续更新 state（导致内存泄漏和警告）等。React Doctor 的规则能够精准捕获这类问题，并给出具体的修复建议。

性能诊断

React Doctor 会分析组件的重渲染模式，识别不必要的 re-render。对于列表渲染，它会检查是否使用了稳定的 key、是否避免了 Index as Key 的反模式。它还会提示可以使用 React.memo 或 useMemo/useCallback 进行优化的地方。

架构与代码组织

好的 React 代码需要清晰的组件边界和合理的状态管理。React Doctor 会检测组件是否过大（建议拆分）、状态是否放在了错误的层级、是否有组件承担了过多职责等问题。

安全风险扫描

在 AI 时代，安全问题更需要警惕。React Doctor 内置了 XSS 防护规则，例如检测 dangerouslySetInnerHTML 的使用（提示使用 sanitize 库）、检测用户输入是否未经校验就渲染等。

无障碍（Accessibility）检查

无障碍是经常被忽视但对产品体验至关重要的维度。React Doctor 会检查图像是否有 alt 属性、表单元素是否有关联 label、按钮是否有可访问的名称等。

多框架兼容

React Doctor 不绑定特定框架。它可以分析 Next.js、Vite+React、Remix、TanStack Router、React Native、Expo 等各种 React 生态项目。只要项目使用 React，React Doctor 就能工作。

使用方式：从 npx 到 CI/CD 全覆盖

React Doctor 提供了三种使用模式，满足不同场景：

快速审计（Quick Start）：在项目根目录运行一行命令即可获得完整的代码审计报告。

npx react-doctor@latest

输出的报告包含问题列表、严重程度评级和综合评分。

AI Agent 集成（Install）：安装后，AI 编程工具（如 Claude Code、Cursor、Codex 等）能够从审计结果中学习，在后续编码时主动避免同类问题。

npx react-doctor@latest install

GitHub Actions CI 集成：将 React Doctor 集成到 PR 流程中，每次 Pull Request 都会自动扫描变更代码，并在 PR 评论区和代码行内标注问题。diff 模式只扫描本次变更的文件，适合大仓库的增量检查。

技术架构：TurboRepo monorepo + 多插件体系

React Doctor 采用 monorepo 架构，使用 pnpm workspace + TurboRepo 管理 6 个子包：

• @react-doctor/core：核心引擎，包含规则执行框架
• @react-doctor/api：CLI 接口和报告生成模块
• @react-doctor/react-doctor：主包，入口点
• eslint-plugin-react-doctor：ESLint 插件版本
• oxlint-plugin-react-doctor：Oxlint 插件版本
• website：官方文档站

项目使用 TypeScript 编写，Node.js >= 20.19.0 为运行要求。ESLint 和 Oxlint 插件的存在意味着用户可以在自己熟悉的工具链中直接使用 React Doctor 的规则，而不必单独安装一个 CLI 工具。

局限与争议

React Doctor 作为一个新兴项目（2024 年底发布），目前规则数量和覆盖面与传统 ESLint 插件（如 eslint-plugin-react）相比还有差距。它的优势在于针对 AI 生成代码场景的专门优化，但在规则深度和生态完整性上仍有成长空间。

此外，React Doctor 专注于静态分析，不提供自动修复功能。对于 AI Agent 场景，修复需要由 AI 工具自行完成；对于人工场景，用户需要手动参考报告进行修改。如果你需要一个能自动修复的类似工具，可以关注 Million 的另一个项目 million.js，或者使用 ESLint 的 --fix 功能结合 eslint-plugin-react。

行业意义与增长趋势

随着 AI 编程工具的普及，AI 生成代码的质量问题正在成为行业共识。React Doctor 的出现代表了一种新思路：不依赖 AI 修复 AI，而是用规则系统为 AI 编程工具设定底线。它与 GitHub Actions 的深度集成，使团队可以把 AI 代码质量门禁固化到 CI 流程中，而不是依赖开发者的个人自觉。

从数据上看，React Doctor 在发布后不到一年内 star 数突破 1.1 万，增长速度在同类型静态分析工具中处于领先。随着 Claude Code、Cursor 等工具继续渗透开发工作流，这类守门员工具的价值会进一步凸显。

图1：React Doctor 品牌标识（暗色主题）

React Doctor 品牌标识，支持亮色/暗色主题自动切换