让编码助手诊断并修复你的 React 代码。

只需一条命令，即可扫描你的代码库中的安全、性能、正确性及架构问题，并输出一个包含可操作诊断信息的 0–100 分 评分。

立即体验 →

https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570

工作原理

React Doctor 会检测你使用的框架（Next.js、Vite、Remix 等）、React 版本以及编译器配置，然后以 并行方式 执行两轮分析：

1. Lint 检查：涵盖状态与副作用、性能、架构、包大小、安全、正确性、无障碍访问以及特定框架（Next.js、React Native）相关的 60 多条规则。这些规则会根据你的项目配置自动启用或禁用。
2. 死代码检测：识别未使用的文件、导出、类型和重复代码。

诊断结果会经过你的配置过滤，并按严重程度打分（错误比警告权重更高），最终生成一个 0–100 的健康评分（75+ 优秀，50–74 需改进，<50 危急）。

安装

在你的项目根目录运行以下命令：

npx -y react-doctor@latest .

使用 --verbose 参数可查看受影响的文件和行号：

npx -y react-doctor@latest . --verbose

为你的编码助手安装

让你的编码助手掌握所有 47 条以上的 React 最佳实践规则。在你的项目根目录运行以下命令：

npx -y react-doctor@latest install

系统会提示你选择要为其安装的已检测到的助手。使用 --yes 参数可跳过提示，直接为所有检测到的助手安装。

支持 Claude Code、Codex、GitHub Copilot、Gemini CLI、Cursor、OpenCode、Factory Droid 和 Pi 等工具。

GitHub Actions

- uses: actions/checkout@v5
  with:
    fetch-depth: 0 # required for --diff
- uses: millionco/react-doctor@main
  with:
    diff: main
    github-token: ${{ secrets.GITHUB_TOKEN }}

输入	默认值	描述
directory	.	要扫描的项目目录
verbose	true	显示每条规则对应的文件详情
project		要扫描的工作区项目（逗号分隔）
diff		用于差异模式的基础分支。仅扫描发生更改的文件
github-token		在 pull_request 事件中设置时，会将发现的问题作为 PR 评论发布
fail-on	error	当出现诊断结果时退出并返回错误码：error、warning 或 none
offline	false	跳过向 react.doctor API 发送诊断信息
node-version	20	要使用的 Node.js 版本

该 Action 会输出一个 score（0–100），你可以在后续步骤中使用。

选项

用法：react-doctor [directory] [options]

选项：
  -v, --version     显示版本号
  --no-lint         跳过 Lint 检查
  --no-dead-code    跳过死代码检测
  --verbose         显示每条规则对应的文件详情
  --score           仅输出分数
  -y, --yes         跳过提示，扫描所有工作区项目
  --project <name>  选择工作区项目（多个项目用逗号分隔）
  --diff [base]     仅扫描与基础分支相比发生变化的文件
  -h, --help        显示命令帮助

浏览器 API

导入 react-doctor/browser 可以运行与 react-doctor/api 的 diagnose 方法相同的 诊断合并、基于配置的过滤、计时和评分流程，但输入参数由调用方提供：包括 project 元数据、一个虚拟的 projectFiles 映射（内容以相对于 rootDirectory 的路径为键），用于解析忽略和抑制规则；以及一个 runOxlint 回调函数，可在你的环境中执行 Lint 检查（例如使用带有 oxlint 的 Web Worker）。

Git 历史、真实文件系统的发现、knip、CLI、暂存文件检测以及交互式提示等功能在浏览器版本中 不可用；这些功能应仅在 Node.js 环境中使用，或者由你自行实现替代方案。react-doctor/worker 重新导出了相同的面向浏览器的模块，适用于 Worker 目标。

如果你在浏览器中直接调用 diagnoseCore，请同时传递来自本包的 calculateDiagnosticsScore 函数（在 react-doctor/browser 中重命名为 calculateScore），以避免捆绑包引入仅限 Node.js 的代理代码。

配置

在你的项目根目录创建一个 react-doctor.config.json 文件，以自定义行为：

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus", "knip/exports"],
    "files": ["src/generated/**"]
  }
}

你也可以在 package.json 中使用 "reactDoctor" 键来代替：

{
  "reactDoctor": {
    "ignore": {
      "rules": ["react/no-danger"]
    }
  }
}

如果两者都存在，react-doctor.config.json 将优先生效。

配置选项

键	类型	默认值	描述
ignore.rules	string[]	[]	要抑制的规则，使用诊断输出中显示的 plugin/rule 格式（例如 react/no-danger、knip/exports、knip/types）
ignore.files	string[]	[]	要排除的文件路径，支持 glob 模式（src/generated/**、**/*.test.tsx）
lint	boolean	true	启用或禁用 lint 检查（与 --no-lint 相同）
deadCode	boolean	true	启用或禁用死代码检测（与 --no-dead-code 相同）
verbose	boolean	false	显示每条规则的文件详情（与 --verbose 相同）
diff	boolean | string	—	强制启用 diff 模式（true）或固定基准分支（"main"）。设置为 false 可禁用自动检测。
failOn	"error" | "warning" | "none"	"none"	当诊断信息达到指定严重级别或更高时，以错误码退出程序
customRulesOnly	boolean	false	禁用内置的 react/jsx-a11y/compiler 规则，仅保留 react-doctor/* 插件规则
share	boolean	true	扫描完成后显示分享结果的 URL
textComponents	string[]	[]	仅适用于 React Native。指定其子组件不应触发 rn-no-raw-text 的组件名称（例如 ["MyText", "Label.Bold"]）

CLI 标志始终会覆盖配置值。

Node.js API

你也可以以编程方式使用 React Doctor：

import { diagnose } from "react-doctor/api";

const result = await diagnose("./path/to/your/react-project");

console.log(result.score); // { score: 82, label: "Good" } 或 null
console.log(result.diagnostics); // Diagnostic 对象数组
console.log(result.project); // 检测到的框架、React 版本等。

diagnose 函数接受一个可选的第二个参数：

const result = await diagnose(".", {
  lint: true, // 运行 lint 检查（默认：true）
  deadCode: true, // 运行死代码检测（默认：true）
});

每个诊断对象的结构如下：

interface Diagnostic {
  filePath: string;
  plugin: string;
  rule: string;
  severity: "error" | "warning";
  message: string;
  help: string;
  line: number;
  column: number;
  category: string;
}

热门开源项目的评分

项目	分数	分享
tldraw	84	查看
excalidraw	84	查看
twenty	78	查看
plane	78	查看
formbricks	75	查看
posthog	72	查看
supabase	69	查看
onlook	69	查看
payload	68	查看
sentry	64	查看
cal.com	63	查看
dub	62	查看

贡献

想贡献代码吗？请查看代码库并提交 PR。

git clone https://github.com/millionco/react-doctor
cd react-doctor
pnpm install
pnpm -r run build

本地运行：

node packages/react-doctor/dist/cli.js /path/to/your/react-project

许可证

React Doctor 是 MIT 许可证下的开源软件。

React Doctor 快速上手指南

React Doctor 是一款专为 React 项目设计的诊断工具，能够自动检测代码库中的安全、性能、正确性及架构问题，并生成 0-100 的健康评分。它支持 Next.js、Vite、Remix 等主流框架，并能与各类 AI 编程助手集成。

环境准备

• 系统要求：支持 Windows、macOS、Linux。
• 前置依赖：
  • 已安装 Node.js (推荐版本 20+)。
  • 拥有一个标准的 React 项目目录（包含 package.json）。
• 网络提示：该工具通过 npx 直接运行，无需全局安装。若国内访问 npm 源较慢，建议配置淘宝镜像或使用代理：

  # 临时使用淘宝镜像运行（如 npx 支持）或配置全局
  npm config set registry https://registry.npmmirror.com
  

安装步骤

React Doctor 无需预先安装到项目中，推荐使用 npx 直接运行最新正式版。

在项目根目录下执行以下命令：

npx -y react-doctor@latest .

提示：-y 参数用于自动确认提示，. 代表扫描当前目录。

基本使用

1. 快速扫描与评分

运行上述安装命令后，工具会自动识别你的框架（Next.js/Vite 等）和 React 版本，并行执行以下检查：

• Lint 检查：覆盖状态管理、副作用、性能、包体积、安全性等 60+ 条规则。
• 死代码检测：查找未使用的文件、导出、类型及重复代码。

扫描完成后，终端将输出一个 0-100 的健康评分：

• 75+：优秀 (Great)
• 50-74：需要改进 (Needs work)
• <50：严重 (Critical)

2. 查看详细报告

若需查看具体受影响的文件路径和行号，请添加 --verbose 参数：

npx -y react-doctor@latest . --verbose

3. 为 AI 编程助手配置

如果你使用 Claude Code、GitHub Copilot、Cursor 等 AI 编程助手，可以运行以下命令将 React 最佳实践规则注入到助手上下文中：

npx -y react-doctor@latest install

• 运行后会提示选择要安装的助手，输入 --yes 可跳过提示并为所有检测到的助手安装。

4. 自定义配置（可选）

在项目根目录创建 react-doctor.config.json 以忽略特定规则或文件：

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**"]
  }
}

或者在 package.json 中添加 "reactDoctor" 字段进行配置。CLI 命令行参数优先级高于配置文件。