创建插件

ESLint 插件通过额外的功能扩展了 ESLint。在大多数情况下，您将通过创建封装您希望在多个项目中共享的额外功能的插件来扩展 ESLint。

创建插件

插件是一个 JavaScript 对象，它向 ESLint 公开了某些属性。

meta - 关于插件的信息。
configs - 包含命名配置的对象。
rules - 包含自定义规则定义的对象。
processors - 包含命名处理器的对象。

要开始，请创建一个 JavaScript 文件并导出一个包含您希望 ESLint 使用的属性的对象。为了使您的插件尽可能易于维护，我们建议您将插件入口文件格式化为如下所示

const plugin = {
    meta: {},
    configs: {},
    rules: {},
    processors: {}
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12

如果您计划将您的插件作为 npm 包分发，请确保导出插件对象的模块是您包的默认导出。这将使 ESLint 能够在命令行中使用--plugin选项指定插件时导入该插件。

插件中的元数据

为了更轻松地调试和更有效地缓存插件，建议在插件根目录的 meta 对象中提供名称和版本，如下所示

const plugin = {

    // preferred location of name and version
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    rules: {
        // add rules here
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

meta.name 属性应与插件的 npm 包名称匹配，meta.version 属性应与插件的 npm 包版本匹配。完成此操作最简单的方法是从您的 package.json 中读取此信息，例如

import fs from "fs";

const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));

const plugin = {

    // preferred location of name and version
    meta: {
        name: pkg.name,
        version: pkg.version
    },
    rules: {
        // add rules here
    }
};

export default plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

或者，您也可以在插件的根目录公开 name 和 version 属性，例如

const plugin = {

    // alternate location of name and version
    name: "eslint-plugin-example",
    version: "1.2.3",
    rules: {
        // add rules here
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

插件中的规则

插件可以公开自定义规则以在 ESLint 中使用。为此，插件必须导出一个 rules 对象，该对象包含规则 ID 到规则的关键值映射。规则 ID 不必遵循任何命名约定，但它不应包含 / 字符（因此它可以是 dollar-sign 但不能是 foo/dollar-sign，例如）。要了解有关在插件中创建自定义规则的更多信息，请参阅自定义规则。

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    rules: {
        "dollar-sign": {
            create(context) {
                // rule implementation ...
            }
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

为了在配置文件中使用来自插件的规则，请导入插件并将其包含在 plugins 键中，并指定一个命名空间。然后，使用该命名空间在 rules 配置中引用规则，如下所示

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        rules: {
            "example/dollar-sign": "error"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13

插件中的处理器

插件可以通过提供 processors 对象来公开可在配置文件中使用的处理器。与规则类似，processors 对象中的每个键都是处理器的名称，每个值都是处理器对象本身。这是一个例子

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    processors: {
        "processor-name": {
            preprocess(text, filename) {/* ... */},
            postprocess(messages, filename) { /* ... */ },
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

为了在配置文件中使用来自插件的处理器，请导入插件并将其包含在 plugins 键中，并指定一个命名空间。然后，使用该命名空间在 processor 配置中引用处理器，如下所示

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/processor-name"
    }
];
1
2
3
4
5
6
7
8
9
10
11

插件中的配置

您可以通过在 configs 键下指定它们来将配置捆绑到插件中。当您想将一组自定义规则与启用推荐选项的配置捆绑在一起时，这很有用。每个插件都支持多个配置。

您可以在也包含在插件中的配置中包含来自插件的单个规则。在配置中，您必须在 plugins 对象中指定您的插件名称以及您要启用的任何属于该插件的规则。任何插件规则都必须以插件命名空间为前缀。这是一个例子

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    configs: {},
    rules: {
        "dollar-sign": {
            create(context) {
                // rule implementation ...
            }
        }
    }
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    recommended: [{
        plugins: {
            example: plugin
        },
        rules: {
            "example/dollar-sign": "error"
        },
        languageOptions: {
            globals: {
                myGlobal: "readonly"
            },
            parserOptions: {
                ecmaFeatures: {
                    jsx: true
                }
            }
        }
    }]
});

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

此插件导出一个 recommended 配置，它是一个包含一个配置对象的数组。当只有一个配置对象时，您也可以只导出该对象而不包含封闭数组。

为了在配置文件中使用来自插件的配置，请导入插件并通过插件对象直接访问该配置。假设该配置是一个数组，请使用扩展运算符将其添加到配置文件返回的数组中，如下所示

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    ...example.configs.recommended
];
1
2
3
4
5
6

测试插件

ESLint 提供了RuleTester 实用程序，使测试插件规则变得容易。

检查插件

ESLint 插件也应该被检查！建议使用以下插件的 recommended 配置来检查您的插件

为了使您的插件公开可用，您必须将其发布到 npm。这样做时，请务必

将 ESLint 列为对等依赖项。因为插件旨在与 ESLint 一起使用，所以将 eslint 包添加为对等依赖项非常重要。为此，手动编辑您的 package.json 文件以包含 peerDependencies 块，如下所示
```
{
    "peerDependencies": {
        "eslint": ">=9.0.0"
    }
}
1
2
3
4
5
```
指定关键字。ESLint 插件应在 package.json 文件中将 eslint、eslintplugin 和 eslint-plugin 指定为关键字。

编辑此页面

创建插件

创建插件

插件中的元数据

插件中的规则

插件中的处理器

插件中的配置

测试插件

检查插件

共享插件