React Doctor：一键量化代码质量，给你的 React 项目打个分

在咱们日常的业务迭代中，React 项目的维护往往会陷入一种“破窗效应”。随着需求堆积，代码库的健康状况往往会经历以下几个阶段的恶化：

• 质量黑盒化：虽然项目能跑，但没人知道隐藏了多少陈旧的 Effect 逻辑或安全漏洞。
• 审计成本高昂：传统的 Code Review 极度依赖人工经验，而标准的 ESLint 又难以触及深层的架构问题。
• AI 引入的副作用：虽然 Cursor、Claude 等工具提升了产出速度，但若缺乏专业规则约束，生成的代码往往会埋下性能隐患。

React Doctor 的出现，正是为了解决这些痛点。

项目介绍

React Doctor 就像是给你项目的代码做“全身体检”，它能自动揪出隐藏的错误和垃圾代码，并给你的项目打出一个直观的 0 到 100 的健康分数。

它不仅能自动识别 Next.js 或 Vite 等框架环境，还能通过并行运行的 60 余条专业 Lint 规则与死代码扫描，针对安全性、性能及架构设计给出深度诊断。

官方网址：https://www.react.doctor/^[1]

项目地址：https://github.com/millionco/react-doctor^[2]

核心功能

1.给代码质量评分

React Doctor 最核心的贡献在于它建立了一套量化的评价体系。它会扫描项目中的安全性、性能、正确性及架构问题，并根据严重程度进行加权计算。

• 痛点描述：团队内部对“代码写得烂”缺乏统一标准，导致重构优先级难以排定。
• 解决方案：输出 0 ~ 100 的健康分（75+ 优秀，50 ~ 74 需改进，<50 为危急），让质量债一眼可见。
• 代码示例：

# 快速获取项目的健康分 npx -y react-doctor@latest . --score

2.Lint 与死代码的深度扫描

不同于传统的单线程检查，React Doctor 会自动识别你的框架环境（Next.js、Vite 等），并并行运行两套分析逻辑：针对 React 最佳实践的 60 余条 Lint 规则，以及对冗余文件、重复类型定义的死代码检测。

• 痛点描述：老项目中存在大量无用的导出和重复类型，手动清理极易出错且效率极低。
• 解决方案：通过并行引擎同时处理逻辑错误与结构冗余，大幅缩短大型项目的审计时间。
• 代码示例：

# 开启详细模式，查看受影响的文件及具体行号 npx -y react-doctor@latest . --verbose

3.为编程助手植入“专家大脑”

这是 React Doctor 最具前瞻性的功能。它可以将 40 多条 React 专家级规则转化为 AI 智能体（如 Cursor、Claude Code）可理解的“技能包”，实现“编写即诊断”的闭环。

• 痛点描述：AI 助手生成的代码有时会违反 React 的闭包陷阱规则或性能最佳实践。
• 解决方案：通过一键安装脚本，让 AI 助手在辅助编程时具备架构师级别的审计眼光。
• 代码示例：

# 为你的 AI 编程助手安装 React 诊断技能 curl -fsSL https://react.doctor/install-skill.sh | bash

4.清单化配置与变更检查

为了确保工具能够平滑集成到咱们的项目中，以下几点核心变更和配置逻辑需要重点对照：

1. 配置优先级：项目根目录的react-doctor.config.json拥有最高优先级，会覆盖package.json中的设置。
2. 规则忽略规范：抑制特定规则时，必须遵循plugin/rule的完整路径格式，例如react/no-danger。
3. CI 环境依赖：在 GitHub Actions 中开启--diff模式时，务必设置fetch-depth: 0以确保 Git 历史完整。
4. 环境最低要求：建议使用 Node.js 20 及以上版本，以获得最佳的并行分析性能。

References

1. https://www.react.doctor/: https://www.react.doctor/
2. https://github.com/millionco/react-doctor: https://github.com/millionco/react-doctor