深入理解 ESLint 扩展体系插件、共享配置、自定义格式化器与解析器完全指南【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 是一个高度可插拔pluggable且可配置的 JavaScript 静态检查工具其核心能力不仅限于内置规则更在于一套完整的扩展机制插件Plugins、共享配置Shareable Configs、自定义格式化器Custom Formatters与自定义解析器Custom Parsers。本文以仓库 docs/src/extend/ways-to-extend.md 为骨架逐层拆解这四类扩展方式的定义、接口、配置方法与底层实现帮助你在真实项目中按需扩展 ESLint 的功能边界。扩展方式总览一个高度可插拔的体系ESLint 的设计哲学是内核尽量精简、能力向外扩展。核心eslint包只内置 JavaScript 解析器与一组核心规则而任何超出内核范围的场景——无论是新的语法、新的文件类型、新的输出格式还是一整套团队规范——都可以通过扩展机制补齐。官方文档将扩展方式归纳为四条主线扩展方式解决什么问题交付形态插件Plugins为项目添加自定义规则、自定义处理器甚至内置共享配置npm 模块eslint-plugin-*共享配置Shareable Configs将整套规则与配置项打包复用npm 模块eslint-config-*自定义格式化器Custom Formatters按自定义格式输出 lint 结果本地文件或 npm 模块eslint-formatter-*自定义解析器Custom Parsers支持新语言特性或自定义语法产出 AST本地文件或 npm 模块这四条主线并非彼此孤立插件是扩展能力的容器可以同时承载规则、处理器、配置与语言language共享配置既可以独立发布也可以作为插件的一部分随插件分发自定义解析器同样可以被包含在插件中。理解它们的接口与协作关系是掌握 ESLint 扩展体系的关键。插件Plugins扩展能力的核心载体插件是什么插件让你能够向项目添加自己的 ESLint 自定义规则custom rules和自定义处理器custom processors并以 npm 模块的形式发布。当项目需要的 ESLint 配置超出了核心eslint包的范围时插件就派上了用场——例如前端框架 React、Vue 所引入的一些特性就需要核心规则之外的专门规则来约束。一个典型的例子是eslint-plugin-react它内置了针对 React 项目的规则包括强制一致地使用组件生命周期方法、在渲染动态列表时要求提供key属性等。插件通常还会搭配一份 ESLint 配置一起使用把插件中的一组特性应用到项目上——这份配置本身也可以直接放在插件里Configs in Plugins。插件对象的结构一个插件本质上就是一个 JavaScript 对象它向 ESLint 暴露若干特定属性。根据 docs/src/extend/plugins.md 的定义插件可以包含meta插件的元信息configs一个包含具名配置的对象rules自定义规则定义的集合processors具名处理器的集合。推荐的插件入口文件结构如下同时兼容 ESM 与 CommonJSconst plugin { meta: {}, configs: {}, rules: {}, processors: {}, }; // for ESM export default plugin; // OR for CommonJS module.exports plugin;为了便于调试与配置缓存建议在插件根部的meta对象中提供name、version和namespaceconst plugin { // preferred location of name and version meta: { name: eslint-plugin-example, version: 1.2.3, namespace: example, }, rules: { // add rules here }, }; // for ESM export default plugin; // OR for CommonJS module.exports plugin;meta.name应与插件 npm 包名一致meta.version应与包版本一致meta.namespace则是用户访问该插件规则、处理器、语言与配置时使用的前缀通常是包名去掉eslint-plugin-后的部分。最稳妥的做法是从package.json中读取这两个值避免手工维护时产生不一致。name与version也可以直接放在插件对象的根部向后兼容的旧格式但meta是推荐位置。在配置文件中使用插件在 flat config 格式下使用插件需要先在plugins键中注册命名空间再通过命名空间/规则名的形式启用规则详见 docs/src/use/configure/plugins.md// eslint.config.js import { defineConfig } from eslint/config; import example from eslint-plugin-example; export default defineConfig([ { files: [**/*.js], // any patterns you want to apply the config to plugins: { example, }, rules: { example/dollar-sign: error, }, }, ]);需要注意命名空间规范不以开头的命名空间不能包含/以开头的可以包含/例如eslint/plugin不合法而eslint/plugin合法。插件也可以从本地文件直接加载本地插件甚至可以在配置中内联定义一个虚拟插件Virtual Plugin把单个规则文件直接包成插件使用。插件内的配置Configs in Plugins插件可以在configs键下打包一份或多份具名配置例如把一组自定义规则和推荐的选项绑定在一起。插件内的配置同样遵循 flat config 的写法在plugins对象中注册自身并启用以命名空间为前缀的规则const plugin { meta: { name: eslint-plugin-example, version: 1.2.3, }, configs: {}, rules: { dollar-sign: { create(context) { // rule implementation ... }, }, }, }; // assign configs here so we can reference plugin Object.assign(plugin.configs, { recommended: [ { plugins: { example: plugin, }, rules: { example/dollar-sign: error, }, languageOptions: { globals: { myGlobal: readonly, }, parserOptions: { ecmaFeatures: { jsx: true, }, }, }, }, ], }); // for ESM export default plugin;使用方通过extends键引用这份具名配置// eslint.config.js import { defineConfig } from eslint/config; import example from eslint-plugin-example; export default defineConfig([ { files: [**/*.js], plugins: { example, }, extends: [example/recommended], }, ]);需要强调插件不能强制用户采用某份配置用户必须在自己的配置文件中显式引入。另外为了兼容 ESLint v9.0.0 之前的 eslintrc 配置体系插件可以用legacy-前缀导出旧格式配置对于已存在recommended命名的老插件也可以增加flat/recommended条目。defineConfig()会先查看recommended键若格式不符再查找flat/recommended键从而提供平滑升级路径。插件的测试、检查与发布测试ESLint 提供了RuleTester工具见 docs/src/integrate/nodejs-api.md 与实现 lib/rule-tester/rule-tester.js可以方便地为插件中的每条规则编写单元测试。检查插件自身也应该被 lint。官方建议使用eslint与eslint-plugin-eslint-plugin、eslint-plugin-n的recommended配置来检查插件代码。发布发布到 npm 时务必在package.json中将eslint声明为peerDependencies例如eslint: 10.0.0并添加eslint、eslintplugin、eslint-plugin关键词便于检索。插件中的自定义规则与处理器插件承载的两种核心扩展物是规则与处理器自定义规则Custom Rules详见 docs/src/extend/custom-rules.md。一条规则导出meta与create(context)两个关键部分meta声明规则的类型problem/suggestion/layout、是否可修复fixable、是否提供建议hasSuggestions、消息模板messages、选项 schemaschema与默认选项defaultOptions等create()返回一组 visitor 方法ESLint 在遍历 AST 时按节点类型、选择器见 docs/src/extend/selectors.md或代码路径事件见 docs/src/extend/code-path-analysis.md调用它们。报告问题统一使用context.report()并推荐以messageId引用meta.messages中集中管理的消息模板。自定义处理器Custom Processors详见 docs/src/extend/custom-processors.md。处理器通过preprocess(text, filename)把非 JS 文件拆分成若干待 lint 的代码块每个代码块含text与filename两个属性再通过postprocess(messages, filename)把多维消息数组合并回一维并校正行号、列号到原始文件坐标。例如eslint/markdown就提供了从 Markdown 文件中提取并 lint 内嵌 JavaScript 的处理器。共享配置Shareable Configs打包整套规范定义与适用场景ESLint 共享配置是预定义好的 ESLint 配置将规则与其他配置项打包进一个 npm 包中供项目直接复用。凡是能写进配置文件的内容都能写进共享配置——规则、languageOptions包括 parser options、plugins、ignores等一应俱全。共享配置可以独立发布也可以作为插件的一部分随插件分发。一个经典的例子是eslint-config-airbnb它包含大量规则并额外指定了一些 parser options设计目的是强制在项目中应用 Airbnb JavaScript 风格指南。通过引入这份共享配置项目无需逐条手工配置规则即可自动落实整套风格规范。创建与发布共享配置本质上就是导出一个配置对象或配置数组的 npm 包详见 docs/src/extend/shareable-configs.md。包名建议遵循eslint-config-*前缀scoped 包则使用scope/eslint-config或scope/eslint-config-myconfig格式以便识别。从包的main入口默认index.js导出配置即可// index.js export default [ { languageOptions: { globals: { MyGlobal: true, }, }, rules: { semi: [2, always], }, }, ];因为index.js只是普通 JavaScript你可以从文件中读取设置甚至动态生成配置。发布时建议在package.json中添加eslint与eslintconfig关键词并用peerDependencies声明对 ESLint 的依赖推荐使用区间语法如eslint: 10.0.0。如果共享配置依赖某个插件或自定义解析器应把这些包放入dependencies。使用与覆盖在eslint.config.js中导入共享配置并通过extends加入导出数组即可// eslint.config.js import { defineConfig } from eslint/config; import myconfig from eslint-config-myconfig; export default defineConfig([ { files: [**/*.js], extends: [myconfig], }, ]);注意共享配置不能与 CLI 的--config标志一起使用。若要在共享配置基础上覆盖某些设置只需在extends之后直接书写同名配置项后续的值会覆盖共享配置// eslint.config.js import { defineConfig } from eslint/config; import myconfig from eslint-config-myconfig; export default defineConfig([ { files: [**/*.js], extends: [myconfig], // anything from here will override myconfig rules: { no-unused-vars: warn, }, }, ]);同一个包还可以导出多份配置除main指定的默认配置外新增文件如my-special-config.js后通过eslint-config-myconfig/my-special-config.js路径直接导入并使用。官方强烈建议始终提供默认导出以避免使用方困惑。自定义格式化器Custom Formatters掌控输出形态格式化器是什么自定义格式化器接收 ESLint 的 lint 结果并以你定义的格式输出——可以是特定文件格式、特定的展示风格也可以是针对某类工具优化的格式。只有当内置格式化器见 docs/src/use/formatters/index.md无法满足需求时才需要自行实现。例如eslint-formatter-gitlab自定义格式化器可以把 ESLint 结果转换为 GitLab 代码质量报告。从源码可以看到ESLint 内核自带四种格式化器lib/cli-engine/formatters/ 目录stylish人类可读输出也是默认格式化器、json、json-with-metadata与html其名称与描述记录在 lib/cli-engine/formatters/formatters-meta.json 中。函数签名与基本用法每个格式化器都是一个函数接收results对象与context两个参数返回一个字符串详见 docs/src/extend/custom-formatters.md。内置 JSON 格式化器实现见 lib/cli-engine/formatters/json.js本质上只有一行//my-awesome-formatter.js module.exports function (results, context) { return JSON.stringify(results, null, 2); };格式化器也可以是 async 函数自 ESLint v8.4.0 起支持//my-awesome-formatter.js module.exports async function (results) { const formatted await asyncTask(); return formatted; };使用-f或--format命令行标志运行自定义格式化器。本地自定义格式化器的路径必须以.开头eslint -f ./my-awesome-formatter.js src/results参数的结构results是一个LintResult对象数组类型定义见 docs/src/integrate/nodejs-api.md每个元素对应一个文件的 lint 结果[ { filePath: /path/to/a/file.js, messages: [ { ruleId: curly, severity: 2, message: Expected { after if condition., line: 2, column: 1, }, { ruleId: no-process-exit, severity: 2, message: Dont use process.exit(); throw an error instead., line: 3, column: 1, }, ], errorCount: 2, warningCount: 0, fixableErrorCount: 0, fixableWarningCount: 0, source: var err doStuff();\nif (err) console.log(failed tests: err);\nprocess.exit(1);\n, }, { filePath: /path/to/Gruntfile.js, messages: [], errorCount: 0, warningCount: 0, fixableErrorCount: 0, fixableWarningCount: 0, }, ];每条message包含ruleId、severity0/1/2、message、line、column等定位信息文件级汇总则通过errorCount、warningCount、fixableErrorCount、fixableWarningCount体现。context参数的结构context是格式化器函数的第二个参数包含以下属性color可选设置--color时为true--no-color时为false两者均未设置时该属性被省略cwd当前工作目录来自ESLint类的cwd构造选项maxWarningsExceeded可选设置了--max-warnings且警告数超出上限时存在含maxWarnings与foundWarnings两个属性rulesMeta各规则的meta属性值可用于在输出中附带规则文档链接等信息。例如运行了no-extra-semi规则时context形如{ cwd: /path/to/cwd, maxWarningsExceeded: { maxWarnings: 5, foundWarnings: 6 }, rulesMeta: { no-extra-semi: { type: suggestion, docs: { description: disallow unnecessary semicolons, recommended: true, url: https://eslint.org/docs/rules/no-extra-semi }, fixable: code, schema: [], messages: { unexpected: Unnecessary semicolon. } } }, }若希望输出点击即可在终端打开文件现代终端普遍支持file:line:column格式按此格式输出即可。向格式化器传递额外参数格式化器函数只接收results与context没有额外的形参。但有两种途径向自定义格式化器注入附加数据通过环境变量——格式化器可以读取环境变量来改变行为。例如用FORMATTER_SKIP_WARNINGS决定是否输出警告module.exports function (results) { var skipWarnings process.env.FORMATTER_SKIP_WARNINGS true; // ... 组装 errors / warnings按 skipWarnings 决定是否包含警告 };运行时FORMATTER_SKIP_WARNINGStrue eslint -f ./my-awesome-formatter.js src/通过管道组合——若自定义格式化器的模式仍不够灵活最稳妥的方案是使用内置 JSON 格式化器把 JSON 输出通过管道交给第二个程序处理eslint -f json src/ | your-program-that-reads-JSON --option打包与发布自定义格式化器可以发布为 npm 包包名遵循eslint-formatter-*格式如eslint-formatter-awesome。使用已发布的格式化器时无需输入eslint-formatter-前缀ESLint 知道在格式化器名不以.开头时去查找eslint-formatter-前缀的包eslint -f awesome src/package.json中main入口必须是实现格式化器的 JavaScript 文件并建议添加eslint、eslint-formatter、eslintformatter关键词方便检索。完整示例一个只输出错误与警告总数的汇总格式化器module.exports function (results, context) { // accumulate the errors and warnings var summary results.reduce( function (seq, current) { seq.errors current.errorCount; seq.warnings current.warningCount; return seq; }, { errors: 0, warnings: 0 }, ); if (summary.errors 0 || summary.warnings 0) { return ( Errors: summary.errors , Warnings: summary.warnings \n ); } return ; };运行eslint -f ./my-awesome-formatter.js src/会输出类似Errors: 2, Warnings: 4。更复杂的详细格式化器则可以逐条输出错误/警告、规则 ID、规则文档链接与file:line:column定位示例见 docs/src/extend/custom-formatters.md 的 Detailed Formatter 一节。自定义解析器Custom Parsers扩展语法边界解析器在 ESLint 中的角色自定义解析器用于扩展 ESLint使其能够 lint 新的非标准 JavaScript 语言特性或代码中的自定义语法。解析器负责把代码转换为抽象语法树ASTESLint 再基于 AST 进行分析与检查。ESLint 自带内置的 JavaScript 解析器 Espree自定义解析器则让你可以 lint 其他语言或扩展内置解析器的能力。例如typescript-eslint/parser就是通过自定义解析器让 ESLint 支持 lint TypeScript 代码。自定义解析器同样可以被包含在插件中。两种方法parse与parseForESLint一个自定义解析器是带有parse()或parseForESLint()方法的 JavaScript 对象详见 docs/src/extend/custom-parsers.md。parse只返回 ASTparseForESLint()除 AST 外还能返回附加信息让解析器更深地定制 ESLint 行为。两个方法都应为实例自身属性第一个参数是源码第二个参数是可选配置对象即配置文件中的parserOptions// customParser.js const espree require(espree); // Logs the duration it takes to parse each file. function parse(code, options) { const label Parsing file ${options.filePath}; console.time(label); const ast espree.parse(code, options); console.timeEnd(label); return ast; // Only the AST is returned. } module.exports { parse };parseForESLint()返回的对象包含必选属性ast与可选属性services、scopeManager、visitorKeysast解析出的 AST 对象services解析器提供的服务如节点的类型检查器规则通过context.sourceCode.parserServices访问默认为空对象scopeManager可替换的ScopeManager对象用于对实验/增强语法做定制化作用域分析默认由eslint-scope创建接口见 docs/src/extend/scope-manager-interface.mdvisitorKeys定制 AST 遍历方式的对象键为 AST 节点类型值为需要遍历的属性名数组默认来自eslint-visitor-keys。解析器同样建议在根部meta中提供name与version与 npm 包名、包版本保持一致便于调试与缓存。AST 规范要点自定义解析器产出的 AST 基于 ESTree 规范但需要额外的位置信息详见 docs/src/extend/custom-parsers.md所有节点必须带range属性两个 0 基索引组成的数组code.slice(node.range[0], node.range[1])必须是该节点的文本loc不能为nullESTree 中它可空但 ESLint 强制要求。所有节点的parent属性必须可写——规则访问 AST 前ESLint 会在遍历中为每个节点设置parent。Program节点必须带tokens与comments属性均为Token接口数组含type、loc、range、value并分别按range[0]排序所有 token 与 comment 的 range 不得互相重叠。Literal节点必须带raw属性即该字面量的源码文本。打包、安装与配置发布自定义解析器时在package.json中把main字段指向导出解析器的文件即可。安装后在 flat config 中用languageOptions.parser指定// eslint.config.js const { defineConfig } require(eslint/config); const myparser require(eslint-parser-myparser); module.exports defineConfig([ { languageOptions: { parser: myparser, }, // ... rest of configuration }, ]);在旧版 eslintrc 配置中则把parser写成字符串// .eslintrc.js module.exports { parser: eslint-parser-myparser, // ... rest of configuration };一个提供parserServices.foo()服务的简单自定义解析器示例// awesome-custom-parser.js var espree require(espree); function parseForESLint(code, options) { return { ast: espree.parse(code, options), services: { foo: function () { console.log(foo); }, }, scopeManager: null, visitorKeys: null, }; } module.exports { parseForESLint };扩展要素的协同一条完整的数据流把四类扩展组合起来可以看到 ESLint 的完整工作链路输入侧自定义解析器把代码解析为 AST内置 JavaScript 语言实现见 lib/languages/js/index.js对于非 JS 文件插件提供的处理器负责从 HTML、Markdown 等文件中提取出代码块再交给 ESLint处理器配置见 docs/src/use/configure/plugins.md 的 Specify a Processor 一节。检查侧插件中的自定义规则随插件注册与核心规则一起在 AST 遍历与代码路径分析中执行插件内附的配置Configs in Plugins或独立发布的共享配置决定启用哪些规则及严重级别。输出侧自定义格式化器接收LintResult数组按目标格式输出给终端、CI 或第三方工具。此外插件还可以提供语言language扩展——通过配置中的language键指定namespace/language-name让 ESLint 直接 lint JavaScript 之外的语言如eslint/json提供的json/jsonc语言。扩展性能的可观测性内置规则耗时统计针对自定义规则的性能分析ESLint 提供了内置的耗时追踪机制设置TIMING环境变量后lint 结束时将显示耗时最长的十条规则及其相对占比时间 规则创建 规则执行。其实现位于 lib/linter/timing.js模块在加载时读取process.env.TIMING决定是否启用统计并在process.on(exit)时输出排序后的规则耗时表格。$ TIMING1 eslint lib Rule | Time (ms) | Relative :-----------------------|----------:|--------: no-multi-spaces | 52.472 | 6.1% camelcase | 48.684 | 5.7% no-irregular-whitespace | 43.847 | 5.1% valid-jsdoc | 40.346 | 4.7% handle-callback-err | 39.153 | 4.6% space-infix-ops | 35.444 | 4.1% no-undefined | 25.693 | 3.0% no-shadow | 22.759 | 2.7% no-empty-class | 21.976 | 2.6% semi | 19.359 | 2.3%从 lib/linter/timing.js 的实现可以看出列表长度默认下限为 10若TIMING为字符串all则输出全部规则若被解析为大于 10 的整数则输出对应条数否则回退到默认 10 条。要单独测试某条规则可组合--no-config-lookup与--rule选项$ TIMING1 eslint --no-config-lookup --rule quotes: [2, double] lib Rule | Time (ms) | Relative :------|----------:|--------: quotes | 18.066 | 100.0%如需更细粒度的耗时信息按文件、按规则可以使用stats选项详见 docs/src/extend/stats.md。总结与进阶路线ESLint 的扩展体系可以概括为插件是承载自定义规则与处理器的容器共享配置让整套规范可打包复用自定义解析器拓宽了可分析的语法范围自定义格式化器则把结果导出为任意需要的形态。四者分别对应 lint 流水线的注册、配置、解析与输出环节既可独立使用也可组合嵌套配置入插件、解析器入插件。深入每个扩展点的实现细节推荐按以下顺序阅读本仓库的对应文档自定义规则docs/src/extend/custom-rules.md含context对象、context.report()、fix 与 suggestions、选项 schema、defaultOptions、作用域访问等完整参考自定义处理器docs/src/extend/custom-processors.md含preprocess/postprocess接口与 autofix 支持插件创建docs/src/extend/plugins.md含插件结构、meta、规则/处理器/配置打包与 legacy 兼容共享配置docs/src/extend/shareable-configs.md自定义格式化器docs/src/extend/custom-formatters.md自定义解析器docs/src/extend/custom-parsers.md同时可结合仓库源码印证内置格式化器位于 lib/cli-engine/formatters/内置规则位于 lib/rules/如 lib/rules/quotes.js、lib/rules/yoda.js、lib/rules/no-shadow.js 分别是选项 schema、多选项规则与作用域分析的典型实现规则的测试工具位于 lib/rule-tester/rule-tester.js。在动手编写自己的第一个自定义规则或格式化器之前先通读这些实现会让你的扩展代码与 ESLint 内核的协作更加顺畅。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考