建立外掛程式

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 資料

為了更容易偵錯和更有效地快取外掛程式，建議在您外掛程式根目錄的 meta 物件中提供 name 和 version，如下所示

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 公用程式，讓您可以輕鬆測試外掛程式的規則。

Lint 外掛程式

ESLint 外掛程式也應該進行 lint！建議使用 recommended 設定來 lint 您的外掛程式

為了讓您的外掛程式公開可用，您必須在 npm 上發佈它。執行此操作時，請務必

將 ESLint 列為同層級相依性。 因為外掛程式旨在與 ESLint 一起使用，所以將 eslint 套件新增為同層級相依性非常重要。若要執行此操作，請手動編輯您的 package.json 檔案以包含 peerDependencies 區塊，如下所示
```
{
    "peerDependencies": {
        "eslint": ">=9.0.0"
    }
}
1
2
3
4
5
```
指定關鍵字。 ESLint 外掛程式應在您的 package.json 檔案中指定 eslint、eslintplugin 和 eslint-plugin 作為關鍵字。

編輯此頁面

建立外掛程式