企业官网建设流程全解析

react-doctor 怎么配置 doctor.config.ts 并控制某条规则的启用与严重级别？

【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor

扫描一个 React 项目后，react-doctor 会把问题按规则分类报出来。当某条规则在你项目里是误报、噪音太大，或者你希望把某条默认只告警的规则升级为错误时，需要把调整写进配置里持久生效。react-doctor 的配置存放在doctor.config.ts（也支持.mts/.cts/.js/.mjs/.cjs/.json/.jsonc），或者package.json的reactDoctor键。所有命令都在项目根目录执行，前提是你已经能用npx react-doctor@latest跑通一次扫描。

先确认配置写在哪：手工写文件还是用 rules 子命令

两种路径都能改同一个文件，选哪条取决于你要不要保留文件里的其他配置：

• 用rules子命令（推荐主路径）：rules set/rules disable/rules category/rules ignore-tag会自动找到当前生效的配置（doctor.config.*优先，其次是package.json#reactDoctor）并原地编辑；TS/JS 配置只同步rules、categories、ignore三个受管字段，其余内容和格式保持不变（通过 magicast 编辑）。如果项目里还没有任何配置，命令会在项目根创建doctor.config.json并写入$schema以便编辑器自动补全。
• 手工写doctor.config.ts：适合一次性写入多段配置。配置查找按扩展名顺序ts, mts, cts, js, mjs, cjs, json, jsonc，同一目录里第一个匹配的文件生效；找不到时向上查找直到项目边界。官方参考文档给出了这样的示例（文档示例）：

// doctor.config.ts export default { rules: { "react-doctor/no-array-index-as-key": "off" }, categories: { "React Native": "warn" }, ignore: { tags: ["design"] }, };

其中rules的键是完整规则键（<plugin>/<rule>形式），值只能是"error"、"warn"、"off"；"off"会让规则跳过注册，即完全不运行、不进入任何输出面；"error"/"warn"则会重新打上规则的严重级别。categories按类别批量调严重级别，ignore.tags按行为标签（如design、test-noise、migration-hint）整族跳过。

另外注意：旧文件名react-doctor.config.json仍可被读取，但已标记为弃用，扫描时会提示改名为doctor.config.json（或手写一个doctor.config.ts）。

控制某一条规则：set、disable、enable

规则键可以用完整键（react-doctor/no-danger）、裸 id（no-danger）或旧式键（react/no-danger）引用。以react-doctor/no-array-index-as-key为例：

# 把某条规则设为指定严重级别（off | warn | error） npx react-doctor@latest rules set react-doctor/no-array-index-as-key warn # 彻底禁用：规则不再运行 npx react-doctor@latest rules disable react-doctor/no-array-index-as-key # 把一条默认关闭（opt-in）的规则按推荐严重级别打开 npx react-doctor@latest rules enable react-doctor/no-array-index-as-key

按意图选命令（来自官方技能文档的决策指南，原则是选最窄的控制）：

• 不认同某条规则、或它是你的误报 →rules disable（写入rules.<key> = "off"，规则到处都不再运行）；
• 规则本身没问题但级别不对 →rules set <rule> warn或rules set <rule> error；
• 想打开一条默认禁用的规则 →rules enable，可选--severity warn|error指定级别，但enable不能设off，要关闭请用disable。

命令成功时的输出形如Set <key> → <severity>，并附一行Updated <配置文件路径>（新建文件会标注 created）。一个例外：如果配置是动态模块（例如export default () => ({...})），CLI 无法静态编辑，会打印出需要合并进默认导出的 JSON 片段并返回非零退出码，这时要手工把该片段应用到配置文件后重跑命令。

更宽的控制面：category 与 ignore-tag

单条规则之外的两个批量开关：

# 整个类别改为某严重级别 npx react-doctor@latest rules category "React Native" off # 按标签整族跳过（例如 design、test-noise 这类行为族） npx react-doctor@latest rules ignore-tag design npx react-doctor@latest rules unignore-tag design

category会校验类别名，未知类别会报错并列出已知类别；ignore-tag同理校验标签名。类型定义文档列出的核心类别是"Security"、"Bugs"、Performance、"Accessibility"、"Maintainability"，技能参考文档里则用"React Native"作为rules category的示例，实际可用列表以rules list输出和 CLI 报错时列出的类别为准。

理解生效规则时，优先级顺序很重要：

1. ignore.tags是 lint 前的门禁：带被忽略标签的规则直接不运行，即使rules或categories把它设为warn/error也无法重新启用；
2. 对没有被标签禁用的规则，rules（单条）覆盖categories（类别）覆盖默认值；
3. 类别级别的严重级别只会重新盖已经启用的规则，永远不会激活一条默认禁用的规则——想 opt-in 必须把该规则本身写进rules。

配置里还有一个buckets字段（目前仅"compiler-cleanup"一个桶，用于在检测到 React Compiler 后把冗余 memoization 规则从 warn 调回"error"），它位于categories与默认值之间；单条rules覆盖仍然压过 bucket。

验证改动是否生效

改完配置有三层验证，从最快到最完整：

# 1. 只列出你的配置改动过的规则及其有效严重级别 npx react-doctor@latest rules list --configured # 也可按类别/标签/框架过滤 npx react-doctor@latest rules list --category Performance npx react-doctor@latest rules list --tag design # 2. 查看某条规则的解释、当前有效严重级别及其来源（rule/category/bucket/tag/default） npx react-doctor@latest rules explain react-doctor/no-array-index-as-key # 3. 重新跑一次扫描确认诊断变化 npx react-doctor@latest --verbose --scope changed

rules explain在 JSON 输出（--json）里会给出severity与source两个字段，能直接判断这条规则现在是按你的rules覆盖、类别覆盖还是默认值在跑；rules list --configured为空说明配置没有实际改动任何规则。第三条命令是官方技能文档中的验证步骤（原文写作--verbose --diff）；CLI 中--diff是--scope changed的弃用别名，运行时会产生告警，建议直接写--scope changed，即只报告相对 base 分支新引入的问题，便于核对禁用/降级后该规则不再出现。

边界与常见误区

• 只想从 PR 评论/评分/CI 门禁里隐藏，但本地仍要看到：不要 disable。这种情况应编辑配置里的surfaces（如surfaces.prComment.excludeRules、surfaces.score.excludeTags、surfaces.ciFailure.excludeCategories），surfaces只控制可见性，不改变规则是否运行。
• warnings: false与单条规则降级的关系：warnings是总开关（默认true），置false后只显示 error 级发现；但被rules/categories显式改标为"warn"的规则仍会显示，它跑在每条规则/类别的严重级别覆盖之后。
• CLI 标志优先于配置：--scope、--blocking等标志会覆盖配置中的同名值，排查"配置好像没生效"时先确认命令行是否传了标志。
• rules值写错会被丢弃：配置加载时会做类型校验，rules/categories里的非法值不会报错展示，而是被丢弃，所以rules list --configured是核对配置真实生效的唯一可靠方式。

配置文件与命令行为的具体定义可继续查阅 配置类型、rules 命令实现、规则配置读写逻辑 与 官方技能参考文档。

【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor