millionco/react-doctor 来源：https://github.com/millionco/react-doctor 版本 (https://npmjs.com/package/react-doctor) 下载量 (https://npmjs.com/package/react-doctor) 如果你的智能体写出了糟糕的 React 代码，它能帮你揪出来。一条命令扫描你的代码库，输出一个 0 到 100 的健康评分 并附带可执行的诊断信息。支持 Next.js、Vite 和 React Native。### 查看演示 → (https://react.doctor) ## 安装 在你的项目根目录运行： bash npx -y react-doctor@latest . 你将获得一个评分（75+ 优秀，50 到 74 需要改进，低于 50 严重）以及涵盖状态与副作用、性能、架构、安全性、无障碍性和无用代码的问题列表。规则会根据你的框架和 React 版本自动切换。 https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570 ## 为你的编码智能体安装 教导你的编码智能体遵循 React 最佳实践，从源头上杜绝编写低质代码。 bash npx -y react-doctor@latest install 系统会提示你选择要安装的已检测到的智能体。传递 --yes 可跳过提示。支持 Claude Code、Cursor、Codex、OpenCode 以及其他 50+ 个智能体。 ## GitHub Actions 此仓库附赠了一个复合动作（Composite Action）。将其放入 .github/workflows/react-doctor.yml： yaml name: React Doctor on: pull_request: push: branches: [main] permissions: contents: read pull-requests: write # 必需用于发布 PR 评论 jobs: react-doctor: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: fetch-depth: 0 # 必需用于 `diff` - uses: millionco/react-doctor@main with: diff: main github-token: ${{ secrets.GITHUB_TOKEN }} 在 pull_request 事件中设置 github-token 后，发现项将作为 PR 评论发布（和更新）。该动作还暴露了一个 score 输出（0–100），可在后续步骤中使用。 输入参数： directory、verbose、project、diff、github-token、fail-on（error / warning / none）、offline、node-version。完整描述请参阅 action.yml (https://github.com/millionco/react-doctor/blob/main/action.yml)。 不想添加市场动作？裸奔的 npx 形式也可以： yaml - run: npx -y react-doctor@latest --fail-on warning ## 配置 在项目根目录创建一个 react-doctor.config.json： json { "ignore": { "rules": ["react/no-danger", "jsx-a11y/no-autofocus"], "files": ["src/generated/**"], "overrides": [ { "files": ["components/modules/diff/**"], "rules": ["react-doctor/no-array-index-as-key", "react-doctor/no-render-in-render"] }, { "files": ["components/search/HighlightedSnippet.tsx"], "rules": ["react/no-danger"] } ] } } 三个嵌套键，三层粒度——选择最适合的最细粒度： - ignore.rules 在整个代码库中静默某个规则。 - ignore.files 在匹配的文件上静默 所有 规则（请谨慎使用——这会丢失无关规则的覆盖率）。 - ignore.overrides 仅在匹配的文件上静默列出的规则，让其他所有规则保持激活。当单个文件（或通配符）确实需要从一两个规则中获得豁免，但仍需扫描其他所有内容时，请使用此项。 你也可以在 package.json 中使用 "reactDoctor" 键。CLI 标志始终覆盖配置值。React Doctor 尊重 .gitignore、.eslintignore、.oxlintignore、.prettierignore 以及 .gitattributes 中的 linguist-vendored / linguist-generated 注释。内联 // eslint-disable* 和 // oxlint-disable* 注释也会被遵守。如果你有 JSON 格式的 oxlint 或 eslint 配置（.oxlintrc.json 或 .eslintrc.json），其规则会自动合并到扫描中并计入分数。设置 adoptExistingLintConfig: false 可选择退出。 #### 可选的配套插件 当以下 ESLint 插件安装在被扫描的项目中（或在你的单体仓库中提升）时，React Doctor 会将它们的规则折叠到同一次扫描中。两者均列为 可选的同级依赖 —— 只安装你想要的。 | 插件 | 新增内容 | 命名空间 | | ———————————————————————————————————————————————– | ———————————————————————————————————————————————————————————————————– | —————— | | eslint-plugin-react-hooks (https://www.npmjs.com/package/eslint-plugin-react-hooks) (v6 或 v7) | React 编译器前端的正确性规则——检测到项目中存在 React 编译器时触发。 | react-hooks-js/* | | eslint-plugin-react-you-might-not-need-an-effect (https://github.com/nickjvandyke/eslint-plugin-react-you-might-not-need-an-effect) (v0.10+) | 补充的“副作用作为反模式”规则（no-derived-state、no-chain-state-updates、no-event-handler、no-pass-data-to-parent 等），与 React Doctor 原生的状态与副作用规则并行运行。 | effect/* | ### 内联抑制 tsx // react-doctor-disable-next-line react-doctor/no-cascading-set-state useEffect(() => { setA(value); setB(value); }, [value]); 当同一行触发两个规则时，你有两个等效的选择。在单行注释中用逗号分隔规则 ID： tsx // react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers, react-doctor/no-derived-useState const [localSearch, setLocalSearch] = useState(searchQuery); 或者在每个规则正上方堆叠一个注释。只要目标行和堆叠注释之间没有其他内容，只有其他 react-doctor-disable-next-line 注释，堆叠注释就会被遵守： tsx // react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers // react-doctor-disable-next-line react-doctor/no-derived-useState const [localSearch, setLocalSearch] = useState(searchQuery); 堆叠注释之间的代码行会中断链条：只有诊断项正上方的注释（以及堆叠在其上的任何连续 react-doctor-disable-next-line 注释）会被遵守。如果注释看起来相邻但规则仍然触发，运行 react-doctor --explain —— 它会报告是否找到了附近的抑制项、覆盖了哪些规则，以及为何未生效。块注释在 JSX 内部也有效： tsx {/* react-doctor-disable-next-line react/no-danger */} 对于多行 JSX，将注释放在开始标签正上方可覆盖整个属性列表（符合 ESLint 惯例）。 ## Lint 插件（独立版）同样的规则集同时作为 oxlint 插件和 ESLint 插件发行，因此你可以将其接入项目现有的任一 lint 引擎。 oxlint 在 .oxlintrc.json 中： jsonc { "jsPlugins": [{ "name": "react-doctor", "specifier": "react-doctor/oxlint-plugin" }], "rules": { "react-doctor/no-fetch-in-effect": "warn", "react-doctor/no-derived-state-effect": "warn", }, } ESLint 扁平化配置： js import reactDoctor from "react-doctor/eslint-plugin"; export default [ reactDoctor.configs.recommended, reactDoctor.configs.next, reactDoctor.configs["react-native"], reactDoctor.configs["tanstack-start"], reactDoctor.configs["tanstack-query"], ]; 完整的规则列表位于 oxlint-config.ts (https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/oxlint-config.ts)。 ## CLI 参考 用法：react-doctor [directory] [options] 选项： -v, --version 显示版本号 --no-lint 跳过代码检查 --no-dead-code 跳过无用代码检测 --verbose 显示每个规则和每文件的详细信息（默认显示前 3 个规则） --score 仅输出分数 --json 输出单一的结构化 JSON 报告 -y, --yes 跳过提示，扫描所有工作区项目 --full 跳过提示，总是运行全量扫描 --project 选择工作区项目（多个用逗号分隔） --diff [base] 仅扫描相对于基准分支变更的文件 --staged 仅扫描暂存的提交文件（用于 pre-commit 钩子） --offline 跳过遥测数据 --fail-on 出现诊断项时退出错误：error, warning, none --annotations 以 GitHub Actions 注解格式输出诊断项 --explain 诊断规则为何触发或抑制为何未生效 --why --explain 的别名 -h, --help 显示帮助 当抑制不生效时，--explain （或其别名 --why ）会报告扫描器在该位置看到的内容，包括为何附近的 react-doctor-disable-next-line 未生效。诊断区分了常见的故障模式——为不同规则设置的相邻注释（使用逗号形式）、注释和诊断项之间存在代码行（链条断裂）、或根本没有附近的抑制项。相同的提示也会在 --verbose 模式下针对每个标记点内联显示，并在 --json 输出中作为 diagnostic.suppressionHint 显示，因此单次扫描即可兼作抑制审计，无需额外标志。 --json 在 stdout 上生成一个可解析的对象，抑制所有人类可读输出。错误仍会产生带有 ok: false 的 JSON 对象，因此 stdout 始终是有效的文档。 ### 配置键 | 键 | 类型 | 默认值 | | ––––––––––––– | –––––––––––––––– | –––– | | ignore.rules | string[] | [] | | ignore.files | string[] | [] | | ignore.overrides | { files, rules? }[] | [] | | lint | boolean | true | | deadCode | boolean | true | | verbose | boolean | false | | diff | boolean \| string | | | failOn | "error" \| "warning" \| "none" | "none" | | customRulesOnly | boolean | false | | share | boolean | true | | textComponents | string[] | [] | | rawTextWrapperComponents | string[] | [] | | respectInlineDisables | boolean | true | | adoptExistingLintConfig | boolean | true | textComponents 是 rn-no-raw-text 的宽泛逃生舱口——列出本身表现得像 React Native 的组件（自定义 `Typography`、`NativeTabs.Trigger.Label` 等），无论其子元素如何，规则都将把它们视为文本容器。 `rawTextWrapperComponents` 是针对那些不是文本元素但安全地将纯字符串子元素通过内部 路由的组件的较窄选项（例如 heroui-native 的 Button，它将子元素字符串化并通过 ButtonLabel 渲染）。列出的包装器仅当其子元素完全可字符串化时才抑制 rn-no-raw-text。拥有混合子元素的包装器——例如 Save ——仍然会报错，因为包装器无法安全地同时在兄弟 JSX 元素旁路由原始文本。 ## Node.js API js import { diagnose, toJsonReport, summarizeDiagnostics } from "react-doctor/api"; const result = await diagnose("./path/to/your/react-project"); console.log(result.score); // { score: 82, label: "Great" } 或 null console.log(result.diagnostics); // Diagnostic[] console.log(result.project); // 检测到的框架、React 版本等。 diagnose 接受第二个参数：{ lint?: boolean, deadCode?: boolean }。 js const report = toJsonReport(result, { version: "1.0.0" }); const counts = summarizeDiagnostics(result.diagnostics); react-doctor/api 重新导出了 JsonReport、JsonReportSummary、JsonReportProjectEntry、JsonReportMode，以及底层的 buildJsonReport 和 buildJsonReportError 构建器。完整类型请参阅 packages/react-doctor/src/api.ts (https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/api.ts)。 ## 排行榜 由 React Doctor 扫描的顶级 React 代码库，按分数排名。根据 millionco/react-doctor-benchmarks (https://github.com/millionco/react-doctor-benchmarks) 自动更新。 | # | 仓库 | 分数 | | – | –– | ––: | | 1 | executor (https://github.com/RhysSullivan/executor) | 94 | | 2 | nodejs.org (https://github.com/nodejs/nodejs.org) | 86 | | 3 | tldraw (https://github.com/tldraw/tldraw) | 70 | | 4 | t3code (https://github.com/pingdotgg/t3code) | 68 | | 5 | better-auth (https://github.com/better-auth/better-auth) | 64 | | 6 | excalidraw (https://github.com/excalidraw/excalidraw) | 63 | | 7 | mastra (https://github.com/mastra-ai/mastra) | 63 | | 8 | payload (https://github.com/payloadcms/payload) | 60 | | 9 | typebot (https://github.com/baptisteArno/typebot.io) | 57 | | 10 | plane (https://github.com/makeplane/plane) | 56 | 查看完整排行榜 (https://www.react.doctor/leaderboard)。 ## 资源与贡献 回顶部 想试试吗？查看演示 (https://react.doctor)。 想贡献回馈？克隆仓库、安装、构建并提交 PR。 bash git clone https://github.com/millionco/react-doctor cd react-doctor pnpm install pnpm build node packages/react-doctor/bin/react-doctor.js /path/to/your/react-project 发现 Bug？前往问题追踪器 (https://github.com/millionco/react-doctor/issues)。 ### 许可 React Doctor 是采用 MIT 许可的开源软件。