ESLint 自定义规则开发
ESLint 自定义规则开发
规则结构（Rule Structure）
每个自定义规则都是一个 JavaScript 模块，需导出一个包含以下必要属性的对象：
meta 元数据
- type：规则类型
"problem"：代码中存在可能导致错误的高优先级问题"suggestion"：代码风格优化建议，不影响功能"layout"：与格式相关的空格、换行等问题
- docs：文档信息
description：规则用途说明url（可选）：详细说明链接
- fixable（可选）：是否支持自动修复
"code"：代码级修复"whitespace"：空白字符修复
- schema：规则配置项的验证方案（基于 JSON Schema）
create(context) 核心方法
返回包含访问者方法的对象，用于遍历 AST 节点：
module.exports = {meta: { ... },create(context) {return {Identifier(node) { ... },"FunctionDeclaration:exit"(node) { ... }};}
};
Context 对象
create 方法接收的 context 参数提供以下关键功能：
属性
| 属性/方法 | 说明 |
|---|---|
context.id | 规则名称 |
context.filename | 当前文件路径 |
context.cwd | 工作目录 |
context.options | 用户配置参数 |
context.sourceCode | 源代码操作对象 |
context.settings | 共享配置 |
context.languageOptions | 语言解析选项 |
方法
context.report(descriptor)：核心问题报告方法context.getSourceCode()（已废弃，推荐使用context.sourceCode）
报告问题（Reporting Problems）
使用 context.report() 报告问题时，可配置以下参数：
- node/loc：问题位置
- message/messageId：错误信息
- 推荐使用
messageId配合meta.messages管理多语言消息
- 推荐使用
- data：消息模板的填充数据
- fix(fixer)：自动修复函数
- suggest：建议修正方案
自动修复注意事项
- 必须在
meta中声明fixable属性 - 常用修复方法：
replaceText()insertTextAfter()removeRange()
- 修复限制：
- 同一位置不可重叠修改
- 最多进行 10 轮修复迭代
占位符与 Message IDs
meta.messages（可选）：定义消息模板对象，其中包含多个 messageId 对应不同错误类型
在 context.report 中通过 messageId + data 引用模板
使用 {{xxx}} 占位符在消息中插入动态内容
选项（Options）与 Schema
可配置规则需满足以下要求：
- 在 meta.schema 中定义配置参数结构（使用 JSON Schema）
- 通过 context.options 获取用户配置值
- 可选提供 defaultOptions 作为未配置项的默认值
- Schema 验证失败会在配置阶段报错，避免运行时异常
源代码访问（Source Code & Comments 等）
通过 context.sourceCode 可进行以下操作：
- 获取源代码：
- 获取完整文本或指定 AST 节点子树 (getText)
- 获取注释信息（注释不在默认 AST 节点中）：
- 获取节点前后注释 (getCommentsBefore/After)
- 获取所有注释 (getAllComments)
- 获取节点内部注释 (getCommentsInside)
- 获取代码结构细节：
- 获取 Token/节点间的空白和注释
- 获取 AST 父节点链 (getAncestors)
作用域（Scopes）与变量追踪
- 使用 sourceCode.getScope(node) 获取节点作用域
- 通过 scope 的 variables 和 references 跟踪变量声明和使用
- 使用 sourceCode.markVariableAsUsed(name, refNode) 标记变量使用
- 避免 no-unused-vars 等规则误报
其他重要事项
- 命名规范：建议遵循核心规则命名风格，保持一致性
- 单元测试：
- 使用 RuleTester 测试
- 包含 valid/invalid 用例
- 验证修复行为
- 运行时规则：
- 支持动态加载规则
- 使用 --rulesdir 指定规则目录
性能分析
- 支持规则性能追踪
- 设置环境变量 TIMING=1 启用性能报告
- 显示最耗时规则及其执行时间占比
- 识别性能瓶颈并进行优化
ESLint 自定义规则的单元测试例子
const rule = require('../../rules/no-js-in-ts-project');
const { RuleTester } = require('eslint');const ruleTester = new RuleTester();
ruleTester.run('no-js-in-ts-project', rule, {valid: [{filename: 'index.ts',code: '',},{filename: '.stylelintrc.js',code: '',},{filename: 'home.ts',code: '',},],invalid: [{filename: 'home.js',code: '',errors: [{message: 'The "home.js" is not recommended in TS project',},],},],
});
测试包含两部分：
✅ 合法用例（valid）
index.ts：允许的 TypeScript 文件.stylelintrc.js：允许的配置文件（如 ESLint/Stylelint 配置通常使用 .js 格式）home.ts：允许的 TypeScript 文件
❌ 非法用例（invalid）
home.js：在 TypeScript 项目中使用 JavaScript 文件将触发错误
错误信息：
The "home.js" is not recommended in TS project
文档参考：ESLint 官方文档中关于自定义规则的部分，详见 ESLint 自定义规则指南