当前位置：首页 > news >正文

ESLint 自定义 Processor（处理器）

news 2025/9/16 7:09:19

ESLint 自定义 Processor（处理器）

🔹 什么是 Processor？

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

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

从非 JS 文件中提取 JS 代码
将 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 } 对象

功能说明：

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

示例：

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

🔹 postprocess（后处理）

输入参数：

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

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

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

🔹 autofix（自动修复支持）

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

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

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

在 Processor 定义中添加：
```
supportsAutofix: true
```

🔹 meta 对象

两种 meta 类型：

插件 meta：

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

用途：

ESLint 配置缓存
显示调试信息

Processor meta：
```
meta: {name: "eslint-processor-name",version: "1.2.3"
}
```
用途：
- 直接引用 Processor 对象时正确识别

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

🔹 配置文件中使用 Processor

两种使用方式：

通过插件名称：

// 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}
]);

直接使用 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"]}
]);