外掛程式遷移至扁平化配置

從 ESLint v9.0.0 開始，預設的設定系統將會是新的扁平化配置系統。為了讓您的外掛程式能夠使用扁平化設定檔，您需要對現有的外掛程式進行一些變更。

建議的外掛程式結構

為了讓您的外掛程式更容易在扁平化配置系統中使用，建議您將現有的外掛程式進入點切換成如下所示

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

此結構在進行本頁討論的其他變更時，可提供最大的彈性。

新增外掛程式元資訊

使用舊的 eslintrc 設定系統時，ESLint 可以從套件名稱中提取有關外掛程式的資訊，但是使用扁平化配置時，ESLint 不再能夠存取外掛程式套件的名稱。為了取代遺失的資訊，您應該新增一個包含至少一個 name 鍵的 meta 鍵，理想情況下，還應該有一個 version 鍵，例如

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.0.0"
    },
    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
13
14
15

如果您的外掛程式是以 npm 套件發佈的，則 name 和 version 應該與 package.json 檔案中的相同；否則，您可以指定任何您想要的值。

如果沒有此元資訊，您的外掛程式將無法與 --cache 和 --print-config 命令列選項一起使用。

遷移適用於扁平化配置的規則

您的外掛程式中的 rules 鍵不需要變更。所有功能都與舊的 eslintrc 設定系統相同。

遷移適用於扁平化配置的處理器

每個處理器都應指定一個 meta 物件。如需更多資訊，請參閱完整文件。

只要您未使用以檔案副檔名命名的處理器，則外掛程式的 processors 鍵不需要進行其他變更。如果您有任何以檔案副檔名命名的處理器，您必須將名稱更新為有效的識別符號（數字和字母）。以檔案副檔名命名的處理器在舊的設定系統中會自動套用，但在使用扁平化配置時不會自動套用。以下是以檔案副檔名命名的處理器的範例

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

        // no longer supported
        ".md": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// 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

名稱 ".md" 對於處理器而言不再有效，因此必須以有效的識別符號取代，例如 markdown

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

        // works in both old and new config systems
        "markdown": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// 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

為了使用這個重新命名的處理器，您還需要在設定中手動指定它，例如

import example from "eslint-plugin-example";

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

如果您已重新命名以檔案副檔名命名的處理器，則應該更新外掛程式的文件，以告知您的使用者。

遷移適用於扁平化配置的設定

如果您的外掛程式匯出會參考回您的外掛程式的設定，則您需要將設定更新為扁平化配置格式。作為遷移的一部分，您需要直接在 plugins 鍵中參考您的外掛程式。例如，以下是以舊設定系統格式匯出的設定，適用於名為 eslint-plugin-example 的外掛程式

// plugin name: eslint-plugin-example
module.exports = {
    configs: {

        // the config referenced by example/recommended
        recommended: {
            plugins: ["example"],
            rules: {
                "example/rule1": "error",
                "example/rule2": "error"
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

若要遷移至扁平化配置格式，您需要將設定移動到建議的外掛程式結構中 plugin 變數的定義之後，如下所示

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

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    recommended: {
        plugins: {
            example: plugin
        },
        rules: {
            "example/rule1": "error",
            "example/rule2": "error"
        }
    }
})

// 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

然後，您的使用者可以使用如下所示的匯出設定

import example from "eslint-plugin-example";

export default [

    // use recommended config
    example.configs.recommended,

    // and provide your own overrides
    {
        rules: {
            "example/rule1": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14

如果您的設定擴充其他設定，則您可以匯出一個陣列

const baseConfig = require("./base-config");

module.exports = {
    configs: {
        extendedConfig: [
            baseConfig,
            {
                rules: {
                    "example/rule1": "error",
                    "example/rule2": "error"
                }
            }
        ],
    },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

您應該更新文件，讓您的外掛程式使用者知道如何參考匯出的設定。

如果您的匯出設定是物件，則您的使用者可以直接將其插入設定陣列中；如果您的匯出設定是陣列，則您的使用者應該使用展開運算子 (...) 將陣列的項目插入設定陣列中。

以下是同時包含物件設定和陣列設定的範例

import example from "eslint-plugin-example";

export default [
    example.configs.recommended, // Object, so don't spread
    ...example.configs.extendedConfig, // Array, so needs spreading
];
1
2
3
4
5
6

如需更多資訊，請參閱完整文件。

遷移適用於扁平化配置的環境

扁平化配置不再支援環境，因此我們建議將您的環境轉換為匯出的設定。例如，假設您匯出一個類似這樣的 mocha 環境

// plugin name: eslint-plugin-example
module.exports = {
    environments: {
        mocha: {
            globals: {
                it: true,
                xit: true,
                describe: true,
                xdescribe: true
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

若要將此環境遷移到設定中，您需要在 plugin.configs 物件中新增一個包含相同資訊的扁平化設定物件的新鍵，如下所示

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

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    mocha: {
        languageOptions: {
            globals: {
                it: "writeable",
                xit: "writeable",
                describe: "writeable",
                xdescribe: "writeable"
            }
        }
    }
})

// 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

然後，您的使用者可以使用如下所示的匯出設定

import example from "eslint-plugin-example";

export default [

    // use the mocha globals
    example.configs.mocha,

    // and provide your own overrides
    {
        languageOptions: {
            globals: {
                it: "readonly"
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

您應該更新文件，讓您的外掛程式使用者知道如何參考匯出的設定。

向後相容性

如果您的外掛程式需要同時使用舊的和新的設定系統，則您需要

匯出 CommonJS 進入點。舊的設定系統無法載入僅以 ESM 格式發佈的外掛程式。如果您的原始碼是 ESM，則您需要使用可以產生 CommonJS 版本的打包工具，並在 package.json 檔案中使用 exports 鍵，以確保 Node.js 可以找到 CommonJS 版本。
保留 environments 鍵。如果您的外掛程式匯出自訂環境，您應該保持它們的現狀，並如上所述匯出等效的扁平化設定。當 ESLint 在扁平化配置模式下執行時，environments 鍵會被忽略。
匯出 eslintrc 和扁平化設定。只有在使用設定時，才會驗證 configs 鍵，因此您可以在 configs 鍵中提供兩種格式的設定。我們建議您在較舊格式的設定中附加 -legacy，以清楚說明這些設定在未來將不再受支援。例如，如果您的主要設定名為 recommended 且為扁平化配置格式，則您也可以有一個名為 recommended-legacy 的設定，該設定為 eslintrc 設定格式。

延伸閱讀

編輯此頁面