ESLint配置怎么弄？eslint配置文件怎么写才能生效？

ESLint 配置不是“规则堆砌”，而是工程质量的“自动化契约”

ESLint 配置的真正价值在于将团队代码规范从“口头约定”转化为“机器强制”，其核心不是追求规则数量，而是建立一套可维护、可扩展、与项目技术栈深度绑定的静态检查体系。 一套优秀的 ESLint 配置应当具备三个特征：规则分层清晰、与格式化工具职责分离、支持渐进式升级，如果只是复制一份流行配置而不理解背后的设计逻辑，反而会陷入“规则噪音”与“误报疲劳”的泥潭。

配置的核心逻辑：从“全量规则”到“场景化预设”

基础层：用 eslint:recommended 兜底

绝大多数项目都不应从零开始写规则。 eslint:recommended 包含了 JavaScript 最常见的语法错误和潜在 bug 检查，比如未定义变量、重复参数、无效正则等，这一层是安全底线，直接启用即可,无需过度讨论。

生态层：按技术栈选择预设

• React 项目：使用 eslint-plugin-react 和 eslint-plugin-react-hooks，hooks 的规则（如 rules-of-hooks）必须开启，因为它能在编译期发现 Hook 调用顺序问题,比运行时崩溃早了几个小时。
• Vue 项目：使用 eslint-plugin-vue 的 vue3-recommended，注意这里要区分 Vue 2 与 Vue 3 的规则差异，不要混用。
• TypeScript 项目：强烈建议让 @typescript-eslint/parser 负责解析，而不是使用默认的 Espree，同时开启 recommended 预设，并额外关注 no-explicit-any 和 no-non-null-assertion 这两条规则它们能有效减少类型逃逸，让 TS 的类型收益真正落地。

项目定制层：将“公司规范”沉淀为“可共享配置”

独立见解：不要直接修改每个项目的 .eslintrc 来适配不同团队成员的习惯，而是创建一个 eslint-config-company 私有 npm 包。 这个包内统一维护基础规则、环境变量、全局变量，并通过 extends 字段被各项目引用，这样，当规则需要更新时，只需发布一个新版本，所有项目 npm update 即可生效，避免了复制粘贴导致规则漂移。

与 Prettier 的分工：别让 ESLint 做“格式化警察”

很多团队在 ESLint 里配置了 indent、quotes、semi 等与排版相关的规则，这是典型的反模式，ESLint 的核心是发现代码质量问题，而 Prettier 的核心是统一代码风格，两者职责交叉会导致冲突max-len 与 Prettier 的换行规则很难完全一致，最终结果就是开发者频繁手动改代码,或者关闭规则。

专业方案是：使用 eslint-config-prettier 关闭 ES Lint 中所有与格式化冲突的规则，然后通过 eslint-plugin-prettier 将 Prettier 作为 ESLint 的一条规则运行。 这样你只需要运行一个命令 eslint . --fix，就能同时完成质量检查和格式修复，且不会出现“改了这里那里又报错”的尴尬。

经验案例：酷番云 CDN 控制台项目的配置演进

酷番云在开发新版 CDN 控制台时，最初直接将 airbnb 配置引入一个多人协作的前端仓库，结果发现代码评审的 60% 时间都花在了“缩进是 2 空格还是 4 空格”这类争论上，而真正逻辑错误的讨论被挤占，后来我们强制采用“ESLint 管质量 + Prettier 管格式”的模式，并基于酷番云 API 网关的特性，定制了一条规则：禁止在业务代码中直接 console.log 打印请求签名参数（通过 no-restricted-syntax

实现），这个配置让新成员在首次提交代码时，就能通过 IDE 内联提示自行修正，而不是在 Code Review 时被反复指出，最终评审效率提升了约 40%，且因为配置是作为 npm 包共享的，酷番云旗下其他内部系统也直接复用，确保跨项目规范一致。

现代化配置：用 Flat Config 告别历史包袱

ESLint v9 之后，默认配置格式从 .eslintrc 过渡到了 eslint.config.js（Flat Config），旧版的 extends 依赖层层覆盖，顺序稍有错误就导致规则失效，Flat Config 的核心优势是以数组形式组织配置对象，每个对象可以指定 files、rules、plugins 等，职责清晰且没有隐式继承。

迁移建议： 若项目从旧版升级，不要一次性全量迁移，而是先保留 .eslintrc 同时创建一个最小化的 eslint.config.js，用 --config 命令行参数指定测试文件，对比新旧检查结果，逐步将每个业务目录纳入新配置，直到旧文件完全废弃,这能显著降低回归风险。

性能优化：不要让 Lint 拖慢开发

• 使用 --cache：ESLint 会生成 .eslintcache 文件，只检查变更过的文件，大型项目可提速 5 倍以上。
• 忽略 node_modules 和构建产物：在配置中显式设置 ignores,避免不必要的文件遍历。
• 按目录拆分配置：如果项目同时包含 Node.js 后端和浏览器前端，通过 overrides（或 Flat Config 的多个配置对象）分别设置 env 与全局变量,避免误报。

相关问答

问 1：为什么我配置了 no-unused-vars，但 TypeScript 项目里仍然有未使用的变量不报错？

答

：这是因为 TypeScript 的解析器与 ESLint 的默认规则存在兼容性问题，你需要使用 @typescript-eslint/no-unused-vars 来覆盖基础规则,正确做法是在配置中这样写：

rules: {
  'no-unused-vars': 'off',
  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
}

注意 argsIgnorePattern 允许以下划线开头的参数不报错，这是处理“回调函数中未使用的前置参数”的常用方案。

问 2：团队成员觉得 ESLint 报错太多，干脆不运行了，怎么办？

答：这是一个体验问题，不是技术问题，解决方案是分层设防：第一层，在 IDE 中安装 ESLint 插件，让错误在敲代码时立刻可见，而不是等提交时才发现；第二层，配置 husky 的 pre-commit 钩子，只对暂存区的文件执行 eslint --fix，让不合规代码根本无法进入提交；第三层，将报错信息映射为“错误级别”而不是“警告级别”，因为警告太多会被忽视，如果团队仍感觉规则苛刻，可以开启一段“过渡期模式”：将部分规则先设置为 warn，并定期召开规则评审会，让开发者参与规则的增删，能显著提升他们的认同感。

配置 ESLint 没有银弹，但有一条清晰的主线：以 recommended 为基础，用共享配置统一团队，与 Prettier 分工明确，最终用 Flat Config 拥抱未来。 如果你正在搭建新项目的 ESLint，不妨从一份极简配置开始，然后在实际代码评审中逐步补充规则。规则是为了让团队更快地交付高质量代码，而不是为了制造障碍。

你在配置 ESLint 时遇到过最头疼的问题是什么？是规则冲突、性能卡顿，还是团队成员不配合？欢迎在评论区分享你的经历,我们一起探讨更优的实践经验。