UD5工具箱
教程：从零开始编写你的第一个自定义 ESLint 规则
本教程将带你一步步完成自定义 ESLint 规则的编写和测试过程。即使你之前从未接触过 ESLint 插件开发，也能跟随本教程快速上手。
第一步：理解 ESLint 规则的基本结构
在开始编写之前，你需要了解 ESLint 自定义规则的基本结构。一条 ESLint 规则本质上是一个导出 create 方法的对象。create 方法接收一个 context 参数，返回一个对象，其键为 AST 节点类型（如 Identifier、CallExpression 等），值为处理对应节点的函数。当 ESLint 解析代码生成 AST 后，会遍历每个节点并调用对应的处理函数。在处理函数中，你可以通过 context.report() 方法报告违规。建议先通过预设规则模板中的 no-console 规则来熟悉这个基本结构。
第二步：配置规则元数据
在规则配置区域，填写规则的基本信息。规则名称应遵循 ESLint 的命名规范，通常以 no- 或 max- 等前缀开头。严重级别选择 error 表示违规会导致构建失败，选择 warn 则仅产生警告。规则描述应清晰地说明该规则的目的和作用，便于其他开发者理解。这些元数据信息会在检测结果中展示，也是发布插件时的重要文档内容。
第三步：选择预设规则或从头编写
如果你是初学者，建议从预设规则模板开始学习。选择一个与你需求接近的预设规则，如 camelcase-naming 用于命名规范检查，或 max-lines-per-function 用于代码复杂度控制。加载预设后，仔细阅读规则函数的实现逻辑，理解每行代码的作用。如果你有明确的需求，也可以清空编辑器从头编写。在编写过程中，利用 context 拥有的各种方法来获取节点信息和报告问题。
第四步：编写测试代码
在测试代码编辑器中输入你希望验证的代码片段。测试代码应该包含两个部分：应该触发规则违规的代码（正例）和不应该触发违规的代码（反例）。例如，如果你编写了一条禁止使用 debugger 语句的规则，测试代码中应同时包含 debugger 语句和不含 debugger 的正常代码。这样可以验证规则既能正确检测违规，又不会误报正常代码。
第五步：运行测试并查看结果
点击运行按钮执行检测。查看结果面板中的检测输出，确认规则是否按照预期工作。如果测试代码中的违规代码被正确标记，而正常代码未被误报，说明规则逻辑正确。如果结果不符合预期，返回规则编辑器检查逻辑是否存在问题。关注检测结果中的行号和列号信息，结合代码预览的高亮标记来定位问题。
第六步：调试与优化规则
调试是规则开发中最关键的环节。如果规则没有检测到预期的违规，可能是 AST 节点类型选择不当或匹配条件过于严格。如果规则产生了误报，可能是匹配范围过宽。建议逐步修改规则逻辑，每次只改变一个条件，然后重新测试以观察变化。利用预设规则作为参考，对比你的实现与标准实现之间的差异。经过反复迭代，直到规则在各种测试用例下都能正确工作。