ESLint 自定义 Processor（处理器）

🔹 什么是 Processor？

在 ESLint 中，Processor（处理器）是一种扩展机制，允许处理非标准 JavaScript/TypeScript 文件。默认情况下，ESLint 仅能处理常规的 JS/TS 文件。

通过自定义处理器，你可以：

1. 从非 JS 文件中提取 JS 代码
2. 将 ESLint 报错信息映射回原始文件

典型应用场景：

• @eslint/markdown 插件：提取 Markdown 文件中的代码块进行检查
• eslint-plugin-vue 插件：处理 Vue 单文件组件中的 <script> 块

🔹 Processor 的基本结构

一个 Processor 需要符合以下接口：

const plugin = {meta: {name: "eslint-plugin-example", // 插件名称version: "1.2.3"              // 插件版本},processors: {"processor-name": {meta: {name: "eslint-processor-name",version: "1.2.3"},preprocess(text, filename) {// text: 文件内容// filename: 文件名return [{ text: code1, filename: "0.js" },{ text: code2, filename: "1.js" }];},postprocess(messages, filename) {// messages: 二维数组 [[msg1, msg2], [msg3]]// 每个子数组对应 preprocess 返回的代码块return [].concat(...messages); // 转换为一维数组},supportsAutofix: true // 是否支持自动修复，默认为 false}}
};// 导出插件对象
module.exports = plugin; // CommonJS
export default plugin;   // ESM

🔹 preprocess（预处理）

输入参数：

• text: 文件内容
• filename: 文件名

返回值：
代码块数组，每个元素包含 { text, filename } 对象

功能说明：

1. 从非 JS 文件中提取 JS 代码
2. 可拆分为多个独立代码块（如 Markdown 中的多个 ```js 代码块）

示例：

• .html 文件：合并所有 <script> 标签为一个代码块
• .md 文件：返回多个独立代码块

🔹 postprocess（后处理）

输入参数：

• messages: 二维数组，每个子数组对应一个代码块的报错信息
• filename: 文件名

返回值：
一维数组，包含最终返回给 ESLint 的报错信息

注意事项：
需要将报错信息中的行号、列号修正为原始文件中的位置，因为 ESLint 报错是基于提取的代码，而用户查看的是原始文件。

🔹 autofix（自动修复支持）

默认情况下 Processor 不支持 --fix 自动修复。要启用该功能：

1. 在 postprocess 中修正 fix 对象的范围：

   fix: {range: [start, end], // 原始文件中的替换范围text: "替换内容"
   }
   

2. 在 Processor 定义中添加：

   supportsAutofix: true
   

🔹 meta 对象

两种 meta 类型：

1. 插件 meta：

   meta: {name: "eslint-plugin-example",version: "1.2.3"
   }
   

   用途：

   • ESLint 配置缓存
   • 显示调试信息

2. Processor meta：

   meta: {name: "eslint-processor-name",version: "1.2.3"
   }
   

   用途：

   • 直接引用 Processor 对象时正确识别

最佳实践：同时为插件和每个 Processor 定义 meta，确保各种使用场景下都能正常工作。

🔹 配置文件中使用 Processor

两种使用方式：

1. 通过插件名称：

   // eslint.config.js
   import { defineConfig } from "eslint/config";
   import example from "eslint-plugin-example";export default defineConfig([{files: ["**/*.txt"], // 处理 .txt 文件plugins: { example },processor: "example/processor-name" // 使用插件中的 processor}
   ]);
   

2. 直接使用 Processor 对象：

   // eslint.config.js
   import { defineConfig } from "eslint/config";
   import example from "eslint-plugin-example";export default defineConfig([{files: ["**/*.txt"],processor: example.processors["processor-name"]}
   ]);
   

🔹 总结

Processor 的核心功能：

• 将非 JS 文件转换为 JS 代码块
• 将报错信息映射回原始文件

主要方法：

• preprocess()：提取代码块
• postprocess()：聚合并修正报错位置

其他特性：

• 默认不支持 --fix，需手动开启
• 推荐同时定义插件和 Processor 的 meta

使用方式：

• plugin-name/processor-name
• 直接访问 processors["xxx"]