react-doctor 如何配合 git pre-commit 钩子只扫描已暂存文件
【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor
你希望每次git commit之前，react-doctor 只检查这次提交暂存（staged）的改动，而不是全仓库重扫。react-doctor 提供--staged扫描模式，它的官方 CLI 帮助里对该标志的描述就是 "scan only staged (git index) files for pre-commit hooks"；配合react-doctor install命令可以装好对应的 git 钩子。完成后，钩子会在提交时执行react-doctor --staged --blocking warning，把已暂存文件中的问题打印到 stderr——按官方说明它是非阻塞设计，提交本身仍会继续，诊断信息只是可见，让你知道要修什么。
前提是一个可用的 git 项目，以及能执行 npx 的 Node 环境。先在项目根目录跑通一次普通审计（README.md 的快速开始）：
npx react-doctor@latest能正常出报告，再进入下面的钩子配置。
安装 react-doctor 的 git 钩子
在项目根目录运行安装命令：
npx react-doctor@latest installCLI 对该命令的定义是 "Install the react-doctor skill into your coding agents and optional git hook"——它同时负责向编码代理安装 skill，以及可选的git 钩子，所以安装过程中有交互提示，git 钩子是其中一项可选项。两个有用的开关（来自 CLI 命令定义）：
--dry-run：show what would be installed without writing files，先预览会安装什么，不写任何文件；-y, --yes：skip prompts, install for all detected agents，跳过提示直接装到所有检测到的代理。
先用--dry-run确认清单，再正式执行，是改动仓库配置前的稳妥做法。
钩子在提交时具体做了什么
生成的 pre-commit 钩子内部固定调用这条命令（见 钩子模板源码）：
react-doctor --staged --blocking warning即只扫描 git 索引里的文件，且把告警级别也当作失败级别（--blocking的可取值为 error（默认）、warning、none，none 表示只做提示）。当暂存内容里发现问题时，钩子向 stderr 打印扫描输出，并附带提示文案：
React Doctor found staged regressions. Run react-doctor --staged --blocking warning to inspect. Want them fixed? Ask your agent to run that command and resolve the findings.
需要注意一个明确的设计决定：这个钩子不阻塞提交。官方 changelog 说明它 "stays non-blocking by design (the commit still proceeds)"，诊断信息现在会被完整输出而不是被吞掉。也就是说，提交后你看到的诊断清单属于"待修问题"，需要回头按提示处理；如果你需要硬性拦截提交，--staged模式本身在发现问题且超过--blocking指定级别时会以失败退出，可以自己写一个会在非零退出码时 abort 的钩子来调用它。
手动只扫已暂存文件
不想依赖钩子、或者只想先验证一次，直接手动运行：
npx react-doctor@latest --staged该模式的语义（来自 CLI 选项定义）：
- 只读 git 索引（staged）中的文件，不含未暂存的工作区改动；
- 遵循
--project参数和配置中的projects字段——在 monorepo 里，每个选中的包会带各自的package.json/tsconfig/ 配置进入 staged 快照，每条暂存路径恰好归属一个包； - 没有暂存内容时，退出码为 0。
如果暂存内容较多，也可以像普通扫描一样显式传文件路径（README.md 中 "Pass file paths to scan only the files that another CI step selected" 的用法）：
npx react-doctor@latest src/a.tsx src/b.tsx但 pre-commit 场景下推荐--staged，它不需要你自己维护文件清单。
结果判断与已知限制
跑完--staged或提交触发钩子后，按以下文档中明确的行为判断结果：
- 配置文件不一致会被拒绝。staged 扫描在 git 索引与工作树的配置不同时会报错退出，而不是用混合快照去扫——目的是防止既漏报又误报。如果你在暂存区里还改了
doctor.config.ts之类的配置文件，先确认索引与工作树一致再扫。 - git 索引读不出来是硬失败。如果 git 命令失败（缺少 git、仓库损坏、权限错误），
--staged会记录警告并明确失败，不会把空结果当成"没有问题"；个别无法快照的路径会被报告并跳过，当最终没有任何可扫文件时，运行给出警告并以 0 退出。 - 未检测到 React 项目不算干净。若扫描目标里解析不出 React/Preact 运行时，stderr 会输出 "No React project detected at
— React rules were gated off; this is not the same as a clean scan."，JSON 报告中 reactDetected为false。对 pre-commit 这类消费方，这条应理解为"扫描目标选错了"，而不是全部通过。 - 全仓检查项在 diff/staged 模式下不跑。项目级安全检查等 whole-project 检查会被
--staged扫描跳过，这与"只扫暂存文件"的目标一致。
验证是否完成：暂存若干有问题的 React 文件后执行npx react-doctor@latest --staged，确认报告只覆盖暂存文件；再走一次git commit，确认钩子在 stderr 打印了上述 staged regressions 提示、提交按非阻塞设计继续进行。之后按提示运行react-doctor --staged --blocking warning逐项修复即可。更多规则开关可以在项目根目录的doctor.config.ts中配置，见 README.md 的 Configure rules 一节。
【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
