React Doctor 是一款专注于 React 代码质量诊断的开源 CLI 工具，其核心设计目标是解决一个日益普遍的问题：AI 编程助手生成代码时频繁出现的反模式、性能缺陷与架构问题。该工具通过 AST（抽象语法树）级别的静态分析，在不依赖运行时的情况下对代码进行全面扫描，并输出一个 0 到 100 的健康评分，帮助开发团队快速定位和修复 AI 生成代码中的质量问题。
AST 级别规则检测的工程原理
React Doctor 的核心扫描引擎基于 AST 分析构建，这意味着它能够深入理解代码的结构而非仅仅匹配字符串模式。当工具执行扫描时，首先会将源代码解析为语法树，然后根据预定义的 60 多条规则对树中的节点进行遍历和匹配。每条规则对应一种已知的反模式或不良实践，例如在渲染方法中调用 setState、在 useEffect 依赖数组中遗漏必要的依赖项、或者将数组索引作为列表渲染的 key 属性。
这种 AST 级别的分析相较于传统的正则表达式匹配或字符串搜索具有显著优势。正则表达式只能检测表面的代码模式，容易产生误报或漏报，而 AST 分析能够准确理解代码的语义上下文。例如，一条检测 “在渲染中调用 setState” 的规则会识别出所有直接在组件的 render 方法或函数组件返回值中调用状态更新函数的代码，即使代码经过格式化、注释或条件包装也不会漏过。规则库覆盖了状态与副作用、性能优化、组件架构、安全性和无障碍访问等多个维度，其中许多规则专门针对 AI 助手常犯的错误模式设计。
规则引擎支持框架自动适配，当检测到项目使用 Next.js、Vite 或 React Native 时，相应的规则子集会自动激活，同时忽略与当前框架无关的检查项。这一特性使得同一配置可以在不同框架的项目中通用，无需为每个项目单独配置规则集。
健康评分体系的量化逻辑
React Doctor 输出的健康评分并非简单的通过或失败统计，而是基于一个经过加权的评分算法。评分分为三个等级区间：75 分及以上标记为 “Great”，表示代码质量良好；50 到 74 分标记为 “Needs work”，提示存在可改进空间；50 分以下则标记为 “Critical”，意味着代码中存在影响应用稳定性或性能的关键问题。
评分算法的权重分配体现了对不同类型问题的优先级判断。安全和可访问性问题通常会获得较高的扣分权重，因为这些问题可能影响最终用户的实际使用体验或带来安全风险。相比之下，代码风格相关的警告扣分权重较低，只在问题积累到一定程度后才会显著影响总分。这种差异化权重设计确保了评分能够真实反映代码的综合质量，而非被大量低优先级的微小问题所主导。
工具默认展示得分最高的三类问题，若要获取完整的诊断列表，可以添加 --verbose 参数。输出格式支持纯文本、JSON 结构化报告以及 GitHub Actions 注解三种模式，其中 JSON 模式便于集成到自动化流水线中进行二次处理或可视化展示。
双路验证：无状态组件误用的自动检测
AI 编程助手在生成 React 组件时经常犯的一个典型错误是混淆有状态组件和无状态组件的使用场景。React Doctor 包含专门检测这类问题的规则，例如 react-doctor/no-derived-useState 用于捕获从 props 或其他状态派生新状态的错误模式。当代码中出现类似 const [localSearch, setLocalSearch] = useState(searchQuery) 的派生状态声明时，规则会立即触发警告，提示开发者考虑使用 useMemo 或直接计算的方式替代。
另一类高频错误是无意识地使用类组件风格编写函数组件，例如在函数组件中创建内部状态但未正确管理副作用。规则 react-doctor/no-render-in-render 用于检测在 JSX 渲染中直接调用返回新组件的函数这种反模式，这类代码会导致每次渲染都创建新的组件引用，破坏 React 的 diffing 算法效率。
对于 useEffect 的依赖管理，React Doctor 集成了 React Compiler 前端的一致性规则，当项目配置了 React Compiler 时会自动启用这些检查。此外，配合 eslint-plugin-react-you-might-not-need-an-effect 插件还能获得额外的 effects 反模式检测能力，包括状态链式更新、事件处理器中的副作用、以及向父组件传递数据等常见误用场景。
依赖遗漏的精确识别
AI 生成的代码另一个常见问题是 useEffect 依赖数组配置不完整，导致闭包陷阱或陈旧值问题。React Doctor 通过分析 useEffect 调用节点的内容以及依赖数组中的变量引用，能够检测出代码实际使用了但未列入依赖数组的变量。例如，当 useEffect 内部读取了某个 state 值但依赖数组中遗漏该变量时，工具会标记这一不一致性。
这种检测基于数据流分析而非简单的字符串匹配。工具会追踪 effect 回调函数内部的变量引用，检查这些变量是否在依赖数组中声明。对于通过解构从 props 获取的值、上下文引用或从外部模块导入的变量，规则会采用不同的检测策略以避免误报。这种精细化的分析确保了警告的准确性，减少了开发者在排查真实问题时的噪音干扰。
快照测试与死代码检测的互补机制
除了 AST 级别的规则检查，React Doctor 还集成了死代码检测功能，用于识别从未被引用的导出、永远不会执行的代码分支以及被注释掉但保留在源码中的废弃逻辑。这项功能对于清理 AI 生成的辅助代码特别有价值，因为 AI 助手往往会生成一些看似有用但实际未被使用的工具函数或组件。
死代码检测采用引用分析技术，首先建立项目的完整依赖图谱，然后遍历所有导出项和文件级引用，标记出没有任何导入路径指向的代码片段。对于条件语句中的不可达分支，工具通过常量表达式求值和分支覆盖分析来识别。这种检测不依赖运行时执行，完全基于静态分析完成，因此可以在 CI 阶段提前发现问题。
死代码检测与 AST 规则检查形成了互补的质量保障体系。前者关注代码的存在性冗余，后者关注代码的正确性缺陷，两者结合能够从多个维度评估 AI 生成代码的整体质量。
CI/CD 集成与 AI 助手集成方案
React Doctor 提供了灵活的集成路径，既可以作为独立的 CLI 工具运行，也可以嵌入到现有的开发和发布流程中。对于 CI/CD 场景，工具提供了专门的 GitHub Actions 集成方案，只需在工作流文件中添加 millionco/react-doctor@main 步骤即可。集成支持 diff 参数进行增量扫描，只检查与主分支相比发生变更的文件，这对于大型项目的 PR 检查非常有价值。
当指定 github-token 后，检查结果会自动发布为 PR 评论，方便代码审查者在不切换界面的情况下查看诊断信息。fail-on 参数支持设置告警阈值，例如 --fail-on warning 会在发现任何警告时使构建失败，确保代码质量标准得到严格执行。
对于 AI 编程助手的集成，React Doctor 提供了一个 install 命令，可以为 Claude Code、Cursor、Codex 等主流 AI 编码工具安装规则集配置。安装后，AI 助手在生成代码时会受到这些规则的约束，从源头减少反模式的产生。这一机制代表了代码质量保障的新范式：不是事后检测和修复，而是在代码生成阶段就进行预防。
可落地的配置参数与最佳实践
在实际项目中部署 React Doctor 时，以下配置参数值得特别关注。ignore.overrides 字段提供了最精细的控制粒度，可以针对特定文件或目录禁用特定规则，同时保持其他规则对该文件的检测覆盖，这种设计适合处理第三方生成的代码或特殊业务场景下的例外情况。
对于 monorepo 项目，--project 参数支持指定需要扫描的子项目名称，多个项目名称可以用逗号分隔。工具会自动识别项目的包管理器、框架类型和 React 版本，适配相应的规则集。在 monorepo 根目录运行扫描时，未指定项目会触发交互式选择提示，--yes 参数可以跳过提示扫描所有子项目。
--explain 参数是诊断抑制注释失效原因的利器，当内联注释未能正确抑制某条警告时，运行 react-doctor --explain file:line 可以获取详细的诊断报告，包括注释是否被识别、规则是否匹配、以及为什么抑制未生效。工具还支持在 package.json 的 reactDoctor 字段中配置所有选项，避免引入额外的配置文件。
inline suppressions 功能支持单行和多行 JSX 场景，注释语法遵循 // react-doctor-disable-next-line rule-id 的格式，多个规则可以用逗号分隔在同一行注释中声明。这一设计保持了与 ESLint 禁用注释的一致性，团队成员无需学习新的语法规范。
资料来源
本文技术细节参考自 React Doctor 官方 GitHub 仓库（https://github.com/millionco/react-doctor）及其文档站点（https://react.doctor/）。
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。