要给 React 项目做一次体检，先别急着全局安装。进入项目根目录，用官方提供的 npx react-doctor@latest 就能启动扫描；@latest 会调用当前最新版，换电脑也不用找全局命令。

安装前先看三项

• 电脑能运行 Node.js，并且终端能识别 node、npm、npx。
• 当前目录是 React、Next.js、Vite、Expo 等项目根目录，能看到 package.json。
• 本地扫描不要求 API Key。官方入口是 react.doctor，仓库是 github.com/millionco/react-doctor。

从项目根目录启动体检

cd /你的/React项目
npx react-doctor@latest

首次运行时，npx 可能先下载包，这是正常现象。想把规则、文件位置和修复提示展开，改用：

npx react-doctor@latest --verbose

这种运行方式不会自动把 react-doctor 写进项目依赖，也不需要先克隆源码。若公司网络限制 npm 下载，先检查代理和 registry，再重试命令，不要从名称相近的镜像站随意取包。

第一次跑完，看哪里

终端出现项目名称、扫描进度、分数、规则编号以及文件行号，就代表工具已工作。首次全量扫描告警多时，先保存结果作为基线，别一口气让 AI 全改。只检查当前分支新增的问题，可执行 npx react-doctor@latest --verbose --scope changed；机器读取结果用 --json，写入指定目录用 --output-dir 路径。修复一项就重跑一次，更容易判断是哪次改动消除了诊断。

命令没反应时怎么查

提示找不到 npx

先执行 node -v 与 npm -v。两条都没有版本号，就先补好 Node.js 环境。

扫描到的文件不对

检查终端所在目录；多项目仓库可用 --project 指定目标，别在仓库外层盲跑。

changed 模式找错基线

用 --base main 明确比较分支；团队主分支不是 main 时，替换为真实名称。

不想发送匿名运行信息

在命令后加 --no-telemetry。官方说明不会上传源文件内容，但受合规要求约束的项目仍可主动关闭。

交付前核对

• 命令能在项目根目录重复执行；
• 终端能定位到具体文件和规则；
• 修复后重跑，目标告警消失且分数没有倒退。