在前端开发的复杂生态中，保障代码质量与规范性是构建稳健、可维护项目的基石。ESLint 作为一款强大的代码检查工具，其默认规则与插件能满足多数常见需求，但面对特定团队规范或项目独特要求，自定义 ESLint 插件便成为有力的扩展手段。本文将深入探讨如何打造自定义 ESLint 插件，并结合实际案例，详细阐述从创建到应用的全过程。
一、ESLint 基础回顾
ESLint 通过静态分析代码，将其转换为抽象语法树（AST），进而依据规则对代码进行细致检查。这一过程始于对代码的解析，默认使用 Espree 解析器，它将代码转化为树形结构，每个节点代表一种语法结构。例如，对于简单代码let num = 10;，在 AST 中会呈现为VariableDeclaration节点。
-
VariableDeclaration节点 ：用于表示变量声明。它包含以下重要属性：
- declarations ：是一个数组，存放变量声明符。在let num = 10;中，这个数组只有一个元素，即表示num变量的声明符。
- kind ：表示声明的类型，如let、const或var。在上述例子中，kind的值为let。
ESLint 利用这些 AST 信息，对照规则库，找出代码中的潜在问题，如未使用的变量、错误的语法等。
二、自定义插件的需求场景
在团队协作项目中，统一的代码风格和规范至关重要。除了常规的代码格式与最佳实践，还可能存在一些特殊要求。例如，为了维护代码的文明性与专业性，我们要求代码中不得出现诸如 "sb250""fuck" 等不文明、不专业的词汇。这类需求无法通过 ESLint 的默认规则实现，因此需要开发自定义插件来满足。
三、自定义 ESLint 插件开发流程
（一）工程搭建
-
初始化项目 ：
- 首先确保全局安装了yo和generator - eslint。若未安装，可通过以下命令进行安装：
javascript
npm i -g yo
npm i -g generator-eslint- 然后创建一个新目录用于插件项目，例如eslint - plugin - yinzhixiaxue，并进入该目录：
javascript
mkdir eslint-plugin-yinzhixiaxue
cd eslint-plugin-yinzhixiaxue-
执行yo eslint:plugin命令，这是一个交互式命令，需要填写相关信息：
- 插件名称：例如eslint-plugin-yinzhixiaxue。
- 插件描述：描述插件的功能，如 "用于检查代码中是否存在不文明词汇的 ESLint 插件"。
- 是否包含自定义规则：选择Yes。
- 是否需要处理器：根据实际需求选择，通常对于简单的规则检查选择No。
-
安装依赖 ：
- 插件开发依赖eslint和eslint-utils库，通过以下命令安装：
javascript
npm install eslint eslint-utils --save - dev（二）创建规则
-
生成规则文件 ：
-
在项目目录下执行npx yo eslint:rule命令，同样是交互式操作：
- 规则名称：例如no-offensive-words。
- 规则描述：如 "禁止在代码中使用不文明词汇"。
- 不通过的案例代码：可输入包含不文明词汇的代码示例，如let message = "fuck you";。
-
完成后，项目目录结构中会生成lib/rules/no-offensive-words.js文件，该文件用于编写具体的规则逻辑。
-
（三）规则配置与编写
- 规则配置（meta对象） ：
在lib/rules/no-offensive-words.js文件中，首先定义meta对象，用于描述规则的元信息：\
javascript
module.exports = {
meta: {
type: 'problem', // 表示该规则识别的代码可能会导致问题，需要优先解决，取值还可以是'suggestion'（建议优化代码）或'layout'（关注代码布局，如空格、分号等）
docs: {
description: '禁止在代码中使用不文明词汇', // 规则的详细描述
category: 'Custom Rules', // 规则的分类，便于在规则列表中进行归类展示
recommended: true, // 表示该规则是否推荐使用，若为true，在继承相关配置时可能会默认启用该规则
url: null // 规则文档的链接，可指向详细介绍该规则的页面，这里暂设为null
},
messages: {
noOffensiveWords: '代码中不允许使用不文明词汇' // 定义规则触发时的错误提示信息，这里的'noOffensiveWords'是一个自定义的标识符，可在后续代码中引用
},
fixable: null, // 表示该规则是否支持自动修复，null表示不支持，'code'表示可修复代码问题，'whitespace'表示可修复空格相关问题
schema: [] // 用于定义规则的配置选项，这里为空表示该规则没有额外的配置参数
},
// 规则具体实现将在create函数中编写
};- AST结构分析与规则编写（create函数） ：
ESLint 通过遍历 AST 来应用规则，因此需要了解代码对应的 AST 结构。对于代码let message = "fuck you";，在 AST Explorer（https://astexplorer.net/）中解析后，VariableDeclaration节点包含message变量的声明信息，而变量的初始值"fuck you"则存储在init属性指向的Literal节点中。
我们使用Literal节点是因为在这个规则中，我们关注的是字符串字面量中是否包含不文明词汇。Literal节点专门用于表示各种字面量，如字符串、数字、布尔值等。在检查不文明词汇时，我们只需要关心字符串类型的字面量，所以使用Literal节点来获取并检查变量值。
基于此，编写create函数来实现规则：\
javascript
module.exports = {
meta: {
// 省略meta部分已有的内容
},
create: function (context) {
const offensiveWords = ['sb250', 'fuck'];
return {
Literal(node) {
if (typeof node.value ==='string') {
offensiveWords.forEach((word) => {
if (node.value.includes(word)) {
context.report({
node,
messageId: 'noOffensiveWords'
});
}
});
}
}
};
}
};在上述代码中：
- 定义了一个包含不文明词汇的数组offensiveWords。
- 在create函数返回的对象中，使用Literal节点访问方法。当 ESLint 遍历 AST 遇到Literal节点（通常用于表示字符串、数字等字面量）时，若其值为字符串类型，则检查该字符串是否包含offensiveWords中的词汇。若包含，则使用context.report方法报告错误，错误信息使用meta.messages中定义的noOffensiveWords。
（四）配置规则组
在lib/rules/index.js文件中，将新创建的规则集成到插件中：
javascript
const requireIndex = require('requireindex');
const rules = requireIndex(__dirname + '/rules');
module.exports = {
rules,
configs: {
recommended: {
plugins: ['yinzhixiaxue'],
rules: {
'yinzhixiaxue/no-offensive-words': 'error'
}
}
}
};这里通过requireIndex引入自定义规则，在configs中定义了recommended配置组，将no-offensive-words规则设置为error级别，即一旦违反该规则，ESLint 将抛出错误。
（五）补充测试用例
在tests/lib/rules/no-offensive-words.js文件中编写测试用例，以验证规则的正确性：
javascript
const rule = require('../../../lib/rules/no-offensive-words');
const RuleTester = require('eslint').RuleTester;
const ruleTester = new RuleTester();
ruleTester.run('no-offensive-words', rule, {
valid: [
'let message = "Hello world";',
'const num = 10;'
],
invalid: [
{
code: 'let message = "sb250 is not allowed";',
errors: [{ messageId: 'noOffensiveWords' }]
},
{
code: 'const greeting = "fuck this";',
errors: [{ messageId: 'noOffensiveWords' }]
}
]
});测试用例分为valid和invalid两组：
- valid组包含符合规则的代码示例，这些代码应通过规则检查。
- invalid组包含违反规则的代码示例，每个示例都指定了预期的错误信息messageId，用于验证规则是否按预期触发错误。
四、自定义插件的使用
（一）插件安装
- 本地调试 ：
在插件项目目录下执行npm link，然后在需要使用该插件的项目目录下执行npm link eslint-plugin-yinzhixiaxue。
- 发布安装 ：
将插件发布到 npm 仓库后，在项目中通过npm install eslint-plugin-yinzhixiaxue --save - dev进行安装。
（二）项目配置
在项目的.eslintrc文件中，添加插件配置：
javascript
{
"extends": ["plugin:yinzhixiaxue/recommended"],
"parserOptions": {
"ecmaVersion": 6,
"sourceType": "module"
}
}这里通过extends继承了eslint-plugin-yinzhixiaxue插件的recommended配置组，同时根据项目需求配置了parserOptions，例如支持 ES6 语法和模块语法。
（三）关于 extends 和 plugins 的深入理解
在 ESLint 的配置体系中，extends和plugins扮演着不同但又紧密关联的角色。
extends主要用于继承已有的配置集合 ，它可以是一个配置文件的路径、可共享配置的名称，或是plugin:插件名/配置组名的形式。以"extends": ["plugin:react/recommended"]为例，它会一次性启用react插件中recommended配置组里预先定义好的多个规则 ，这些规则涵盖了插件作者认为在大多数情况下适合项目使用的代码检查规范，比如react/jsx-uses-react、react/jsx-uses-vars等规则会同时生效，无需开发者逐个配置。这大大简化了配置流程，确保项目遵循特定插件推荐的整体规则集。
plugins则是用于引入第三方插件 ，扩展 ESLint 的功能边界。在使用插件前，需要先通过npm安装插件，然后在.eslintrc文件的plugins数组中添加插件名，如"plugins": ["eslint-plugin-demo"] 。引入插件后，若想启用插件中的规则，有两种常见方式。一是在rules中单独配置，例如想启用eslint-plugin-demo插件中的rule1规则，可以设置"eslint-plugin-demo/rule1": "error" ，这种方式适用于对插件规则有精细化控制，只启用部分规则的场景；二是结合extends，通过继承插件提供的配置组来批量启用规则，就像前面提到的"extends": ["plugin:react/recommended"] 。
extends会默认开启当前的所有，plugin需要自己手动开启
extends侧重于对已有配置的复用 ，让开发者能够快速应用一套成熟的规则体系；而plugins更专注于引入新的功能，无论是自定义规则还是特殊文件处理器。在实际项目中，二者通常相互配合，开发者可以根据项目的具体需求，先用plugins引入插件，再巧妙运用extends来启用插件中合适的配置组，从而精准定制出符合项目特点的代码检查方案。
通过以上步骤，我们成功创建并应用了一个自定义 ESLint 插件，能够有效检查代码中是否存在不文明词汇，进一步提升了代码的规范性与专业性，为团队协作和项目维护提供了有力保障。在实际开发中，可根据更多具体需求，灵活扩展和调整自定义插件的规则，以满足不断变化的项目要求。
技术交流沟通➕V：yinzhixiaxue