在大型前端项目中，我们常借助社区插件来扩展 ESLint 的检查能力，但多数插件自带几十条规则。如果一股脑全部开启，不仅终端被无意义警告刷屏，还会拖慢编辑器响应。实际做法应当是只把业务真正需要的那几条规则打开，其余保持关闭或由默认层级控制。
理解 ESLint 插件的规则命名空间
ESLint 插件通常以 npm 包形式发布，包名多为 eslint-plugin-xxx。在配置里通过 plugins 数组声明后，该插件提供的规则都会挂在对应的命名空间下。比如安装了 eslint-plugin-react 并在配置中写了 plugins: ['react']，那么所有 react 插件规则都必须以 react/ 作为前缀来引用。
很多初学者误以为在 extends 里写了 plugin:react/recommended 就只能用推荐集，其实推荐集只是官方帮你选好的一组规则开启项。你可以同时既继承推荐集，又在 rules 里单独覆盖或追加某条规则。命名空间机制保证了不同插件之间的规则不会互相冲突，也让我们能精确定位到某一条规则。
仅启用插件中特定规则的配置方式
最干净的做法是：不在 extends 中引入插件的整包规则集，而是只把插件声明进去，随后在 rules 中手动列出要启用的规则。下面以 eslint-plugin-import 为例，只开启其中的 import/no-unresolved 和 import/named 两条。
// .eslintrc.js
module.exports = {
root: true,
parserOptions: {
ecmaVersion: 2020,
sourceType: 'module'
},
plugins: ['import'],
extends: [
'eslint:recommended'
],
rules: {
// 只启用 import 插件中的两条特定规则
'import/no-unresolved': 'error',
'import/named': 'warn'
}
};
上述配置没有使用 plugin:import/recommended，因此 import 插件的其他几十条规则都不会生效。这样团队成员运行 lint 时，只会收到和模块引用正确性直接相关的提示，大幅降低干扰。如果后续想加一条 import/order，只需在 rules 里补一行即可，改动非常局部。
对于使用 JSON 格式配置文件的场景，写法完全一致，只是去掉了注释。需要注意 JSON 里不能写 trailing comma，且所有键名必须用双引号。无论哪种格式，规则值可以是 off、warn、error，或者用数字 0、1、2 表示，但字符串形式可读性更好。
常见错误配置与对比
一种典型错误是图省事直接 extends 整个插件推荐集，然后发现某条规则太严又去一一关闭。这种方式不仅配置冗长，而且插件升级后新增的规则会默认开启，导致构建突然失败。
// 不推荐：先全开再关，维护成本高
module.exports = {
extends: ['plugin:import/recommended'],
rules: {
'import/no-named-as-default': 'off',
'import/no-named-as-default-member': 'off',
'import/no-cycle': 'off'
// 插件更新后可能冒出新的默认开启规则
}
};
对比之下，白名单式配置（只写要开的）在可预测性上明显占优。我们可以用一张表来看差异：
| 配置策略 | 规则可控性 | 升级风险 | 配置体积 |
|---|---|---|---|
| 继承整包推荐集再关闭 | 低，需手动排除 | 高，新增规则自动生效 | 大 |
| 仅声明插件并逐条开启 | 高，显式白名单 | 低，未写规则永不生效 | 小 |
结合 overrides 按目录精细启用
有时某些插件规则只适合在特定目录生效，比如测试文件允许使用 import/no-unresolved 的宽松模式。这时可以用 overrides 字段，针对文件匹配模式单独启用插件规则。
module.exports = {
plugins: ['import'],
rules: {
'import/no-unresolved': 'error'
},
overrides: [
{
files: ['**/__tests__/**/*.js'],
rules: {
// 测试目录把同一条插件规则降为警告
'import/no-unresolved': 'warn'
}
}
]
};
这种分层方式让插件特定规则既能全局少量开启，又能局部微调。它避免了为不同目录维护多份独立配置文件，也符合 ESLint 级联解析的设计思路。只要记住规则全名带命名空间，配置就不会偏离预期。
验证配置是否生效
写完配置后，建议用命令行直接运行 npx eslint --print-config 某个文件.js 来查看最终合并后的配置，确认目标插件规则的确处于开启状态，且其他规则为 off。也可以故意写一段触发该规则的代码，执行 lint 看是否报错。
// demo.js 用于验证 import/no-unresolved
import { foo } from './not-exist-module';
console.log(foo);
如果配置正确，执行 npx eslint demo.js 会报出模块未找到的错误；若规则没启用则毫无提示。通过这种小步验证，能保证线上 CI 中的 ESLint 行为和你本地完全一致，避免“我本地没报错”的扯皮情况。
ESLintplugin_rulesconfiguration修改时间：2026-08-09 22:48:35