建立外掛程式

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 指定為關鍵字。

編輯此頁面

建立外掛程式