版本

組態遷移指南

本指南概述如何將您的 ESLint 組態檔案從 eslintrc 格式（通常在 .eslintrc.js 或 .eslintrc.json 檔案中設定）遷移到新的扁平組態格式（通常在 eslint.config.js 檔案中設定）。

若要深入了解扁平組態格式，請參閱這篇部落格文章。

有關這些組態格式的參考資訊，請參閱以下文件

遷移您的組態檔案

若要開始使用，請在您現有的組態檔案 (.eslintrc、.eslintrc.json、.eslintrc.yml) 上使用組態遷移器，如下所示

npx @eslint/migrate-config .eslintrc.json

這將為您的 eslint.config.js 檔案建立一個起點，但不保證無需進一步修改即可立即運作。但是，它會自動完成本指南中提到的大部分轉換工作。

開始使用扁平組態檔案

自 ESLint v9.0.0 起，扁平組態檔案格式已成為預設組態檔案格式。您可以開始使用扁平組態檔案格式，而無需任何其他組態。

若要將扁平組態與 ESLint v8 搭配使用，請將 eslint.config.js 檔案放置在您專案的根目錄或將 ESLINT_USE_FLAT_CONFIG 環境變數設定為 true。

組態檔案格式之間未變更的事項

雖然組態檔案格式已從 eslintrc 變更為扁平組態，但以下內容保持不變

  • 設定規則的語法
  • 設定處理器的語法
  • CLI，除了CLI 旗標變更中提到的旗標變更外。
  • 全域變數的設定方式相同，但在不同的屬性上（請參閱設定語言選項）。

組態格式之間的關鍵差異

eslintrc 和扁平組態格式之間一些最顯著的差異如下

匯入外掛程式和自訂解析器

Eslintrc 檔案在 plugins 屬性內使用基於字串的匯入系統來載入外掛程式，並在 extends 屬性內載入外部組態。

扁平組態檔案將外掛程式和解析器表示為 JavaScript 物件。這表示您可以使用 CommonJS require() 或 ES 模組 import 陳述式從外部檔案載入外掛程式和自訂解析器。

例如，此 eslintrc 組態檔案會載入 eslint-plugin-jsdoc 並設定該外掛程式的規則

// .eslintrc.js

module.exports = {
    // ...other config
    plugins: ["jsdoc"],
    rules: {
        "jsdoc/require-description": "error",
        "jsdoc/check-values": "error"
    }
    // ...other config
};

在扁平組態中，您會執行相同的操作，如下所示

// eslint.config.js

import jsdoc from "eslint-plugin-jsdoc";

export default [
    {
        files: ["**/*.js"],
        plugins: {
            jsdoc: jsdoc
        },
        rules: {
            "jsdoc/require-description": "error",
            "jsdoc/check-values": "error"
        }
    }
];

自訂解析器

在 eslintrc 檔案中，匯入自訂解析器類似於匯入外掛程式：您使用字串來指定解析器的名稱。

在扁平組態檔案中，將自訂解析器匯入為模組，然後將其指派給組態物件的 languageOptions.parser 屬性。

例如，此 eslintrc 組態檔案使用 @babel/eslint-parser 解析器

// .eslintrc.js

module.exports = {
    // ...other config
    parser: "@babel/eslint-parser",
    // ...other config
};

在扁平組態中，您會執行相同的操作，如下所示

// eslint.config.js

import babelParser from "@babel/eslint-parser";

export default [
    {
        // ...other config
        languageOptions: {
            parser: babelParser
        }
        // ...other config
    }
];

處理器

在 eslintrc 檔案中，處理器必須在一個外掛程式中定義，然後在組態中依名稱參考。以點開頭的處理器表示檔案副檔名命名的處理器，ESLint 會自動為該檔案副檔名設定。

在扁平組態檔案中，處理器仍然可以從外掛程式中依其名稱參考，但它們現在也可以直接插入到組態中。處理器永遠不會自動設定，必須在組態中明確設定。

以下是一個包含處理器的自訂外掛程式的範例

// node_modules/eslint-plugin-someplugin/index.js
module.exports = {
    processors: {
        ".md": {
            preprocess() {},
            postprocess() {}
        },
        "someProcessor": {
            preprocess() {},
            postprocess() {}
        }
    }
};

在 eslintrc 中，您會如下設定

// .eslintrc.js
module.exports = {
    plugins: ["someplugin"],
    processor: "someplugin/someProcessor"
};

ESLint 也會自動新增以下內容的等效項

{
     overrides: [{
        files: ["**/*.md"],
        processor: "someplugin/.md"
     }]
}

在扁平組態中，以下都是表達相同內容的有效方式

// eslint.config.js
import somePlugin from "eslint-plugin-someplugin";

export default [
    {
        plugins: { somePlugin },
        processor: "somePlugin/someProcessor"
    },
    {
        plugins: { somePlugin },
        // We can embed the processor object in the config directly
        processor: somePlugin.processors.someProcessor
    },
    {
        // We don't need the plugin to be present in the config to use the processor directly
        processor: somePlugin.processors.someProcessor
    }
];

請注意，由於 .md 處理器不是由扁平組態自動新增的，因此您還需要指定一個額外的組態元素

{
    files: ["**/*.md"],
    processor: somePlugin.processors[".md"]
}

基於 Glob 的組態

依預設，eslintrc 檔案會分析它們所在目錄及其子目錄中的所有檔案（.eslintignore 涵蓋的檔案除外）。如果您想對不同的檔案 glob 模式使用不同的組態，可以在 overrides 屬性中指定它們。

依預設，扁平組態檔案在匯出的陣列中支援不同的基於 glob 模式的組態。您可以在組態物件的 files 屬性中包含 glob 模式。如果您未指定 files 屬性，則組態預設為 glob 模式 "**/*.{js,mjs,cjs}"。基本上，扁平組態檔案中的所有組態都類似於 eslintrc overrides 屬性。

eslintrc 範例

例如，此 eslintrc 檔案適用於它所在目錄及其子目錄中的所有檔案

// .eslintrc.js

module.exports = {
    // ...other config
    rules: {
        semi: ["warn", "always"]
    }
};

此 eslintrc 檔案支援具有覆寫的多個組態

// .eslintrc.js

module.exports = {
    // ...other config
    overrides: [
        {
            files: ["src/**/*"],
            rules: {
                semi: ["warn", "always"]
            }
        },
        {
            files:["test/**/*"],
            rules: {
                "no-console": "off"
            }
        }
    ]
};

對於扁平組態，以下是具有預設 glob 模式的組態

// eslint.config.js

import js from "@eslint/js";

export default [
    js.configs.recommended, // Recommended config applied to all files
    // Override the recommended config
    {
        rules: {
            indent: ["error", 2],
            "no-unused-vars": "warn"
        }
        // ...other configuration
    }
];

支援不同 glob 模式的多個組態的扁平組態範例

// eslint.config.js

import js from "@eslint/js";

export default [
    js.configs.recommended, // Recommended config applied to all files
    // File-pattern specific overrides
    {
        files: ["src/**/*", "test/**/*"],
        rules: {
            semi: ["warn", "always"]
        }
    },
    {
        files:["test/**/*"],
        rules: {
            "no-console": "off"
        }
    }
    // ...other configurations
];

設定語言選項

在 eslintrc 檔案中，您可以在 env、globals 和 parserOptions 屬性中設定各種語言選項。特定執行階段的全域變數群組（例如，瀏覽器 JavaScript 的 document 和 window；Node.js 的 process 和 require）會使用 env 屬性設定。

在扁平組態檔案中，globals 和 parserOptions 會整合在 languageOptions 鍵下；env 屬性不存在。特定執行階段的全域變數群組會從 globals npm 套件匯入，並包含在 globals 屬性中。您可以使用展開運算子 (...) 一次匯入多個全域變數。

例如，以下是一個具有語言選項的 eslintrc 檔案

// .eslintrc.js

module.exports = {
    env: {
        browser: true,
        node: true
    },
    globals: {
        myCustomGlobal: "readonly",
    },
    parserOptions: {
        ecmaVersion: 2022,
        sourceType: "module"
    }
    // ...other config
}

以下是扁平組態中相同的組態

// eslint.config.js

import globals from "globals";

export default [
    {
        languageOptions: {
            ecmaVersion: 2022,
            sourceType: "module",
            globals: {
                ...globals.browser,
                ...globals.node,
                myCustomGlobal: "readonly"
            }
        }
        // ...other config
    }
];

eslint-env 組態註解

在 eslintrc 組態系統中，可以使用 eslint-env 組態註解來定義檔案的全域變數。當使用扁平組態進行靜態程式碼分析時，不再識別這些註解：在未來版本的 ESLint 中，eslint-env 註解將會回報為錯誤。因此，從 eslintrc 遷移到扁平組態時，應從所有檔案中移除 eslint-env 組態註解。它們可以被等效但更詳細的 global 組態註解取代，或捨棄而改用組態檔案中的 globals 定義。

例如，當使用 eslintrc 時，要進行靜態程式碼分析的檔案可能如下所示

// tests/my-file.js

/* eslint-env mocha */

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});

在以上範例中，由於 /* eslint-env mocha */ 註解，describe 和 it 會被識別為全域識別碼。

使用 global 組態註解，在扁平組態中可以達到相同的效果，例如

// tests/my-file.js

/* global describe, it -- Globals defined by Mocha */

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});

另一個選項是從要進行靜態程式碼分析的檔案中移除註解，並在組態中定義全域變數，例如

// eslint.config.js

import globals from "globals";

export default [
    // ...other config
    {
        files: [
            "tests/**"
        ],
        languageOptions: {
            globals: {
                ...globals.mocha
            }
        }
    }
];

預先定義和可分享的組態

在 eslintrc 檔案中，使用 extends 屬性來使用預先定義和可分享的組態。ESLint 隨附兩個您可以作為字串存取的預先定義組態

  • "eslint:recommended"：ESLint 建議的規則
  • "eslint:all"：ESLint 隨附的所有規則

您也可以使用 extends 屬性來擴充可分享的組態。可分享的組態可以是本機組態檔案的路徑或 npm 套件名稱。

在扁平組態檔案中，預先定義的組態會從個別模組匯入到扁平組態檔案中。recommended 和 all 規則組態位於 @eslint/js 套件中。您必須匯入此套件才能使用這些組態

npm install @eslint/js --save-dev

您可以將這些組態的每一個新增到匯出的陣列中，或從它們公開特定的規則。您必須使用扁平組態匯入本機組態檔案和 npm 套件組態的模組。

例如，以下是一個使用內建 eslint:recommended 組態的 eslintrc 檔案

// .eslintrc.js

module.exports = {
    // ...other config
    extends: "eslint:recommended",
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}

此 eslintrc 檔案使用內建組態、本機自訂組態和來自 npm 套件的可分享組態

// .eslintrc.js

module.exports = {
    // ...other config
    extends: ["eslint:recommended", "./custom-config.js", "eslint-config-my-config"],
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}

若要在扁平組態中使用相同的組態，您會執行以下操作

// eslint.config.js

import js from "@eslint/js";
import customConfig from "./custom-config.js";
import myConfig from "eslint-config-my-config";

export default [
    js.configs.recommended,
    customConfig,
    myConfig,
    {
        rules: {
            semi: ["warn", "always"]
        },
        // ...other config
    }
];

請注意，由於您只是匯入 JavaScript 模組，因此您可以在 ESLint 使用組態物件之前修改它們。例如，您可能只想讓某些組態物件僅適用於您的測試檔案

// eslint.config.js

import js from "@eslint/js";
import customTestConfig from "./custom-test-config.js";

export default [
    js.configs.recommended,
    {
        ...customTestConfig,
        files: ["**/*.test.js"],
    },
];

在扁平組態中使用 eslintrc 組態

您可能會發現您依賴的可分享組態尚未更新為扁平組態格式。在這種情況下，您可以使用 FlatCompat 公用程式將 eslintrc 格式轉換為扁平組態格式。首先，安裝 @eslint/eslintrc 套件

npm install @eslint/eslintrc --save-dev

接著，導入 FlatCompat 並建立一個新的實例，以轉換現有的 eslintrc 設定。例如，如果 npm 套件 eslint-config-my-config 是 eslintrc 格式，你可以這樣寫：

import { FlatCompat } from "@eslint/eslintrc";
import path from "path";
import { fileURLToPath } from "url";

// mimic CommonJS variables -- not needed if using CommonJS
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const compat = new FlatCompat({
    baseDirectory: __dirname
});

export default [

    // mimic ESLintRC-style extends
    ...compat.extends("eslint-config-my-config"),
];

這個範例使用 FlatCompat#extends() 方法將 eslint-config-my-config 插入到扁平化的設定陣列中。

如需更多關於 FlatCompat 類別的資訊，請參閱套件的 README。

忽略檔案

使用 eslintrc 時，你可以透過在專案根目錄建立一個獨立的 .eslintignore 檔案來讓 ESLint 忽略檔案。.eslintignore 檔案使用與 .gitignore 檔案相同的 glob 模式語法。或者，你也可以在你的 eslintrc 檔案中使用 ignorePatterns 屬性。

若要使用扁平化設定來忽略檔案，你可以在一個沒有其他屬性的設定物件中使用 ignores 屬性。ignores 屬性接受一個 glob 模式的陣列。扁平化設定不支援從 .eslintignore 檔案載入忽略模式，因此你需要將這些模式直接遷移到扁平化設定中。

例如，這裡有一個你可以與 eslintrc 設定一起使用的 .eslintignore 範例：

# .eslintignore
temp.js
config/*
# ...other ignored files

以下是在 .eslintrc.js 檔案中表示為 ignorePatterns 的相同模式：

// .eslintrc.js
module.exports = {
    // ...other config
    ignorePatterns: ["temp.js", "config/*"],
};

在扁平化設定中，等效的忽略模式如下所示：

export default [
    // ...other config
    {
        // Note: there should be no other properties in this object
        ignores: ["**/temp.js", "config/*"]
    }
];

在 .eslintignore 中，temp.js 會忽略所有名為 temp.js 的檔案，而在扁平化設定中，你需要將其指定為 **/temp.js。扁平化設定中的模式 temp.js 只會忽略與設定檔位於同一目錄下名為 temp.js 的檔案。

靜態程式碼分析器選項

Eslintrc 檔案允許你使用 noInlineConfig 和 reportUnusedDisableDirectives 屬性來設定 linter 本身。

扁平化設定系統引入了一個新的頂層屬性 linterOptions，你可以用它來設定 linter。在 linterOptions 物件中，你可以包含 noInlineConfig 和 reportUnusedDisableDirectives。

例如，這是一個啟用 linter 選項的 eslintrc 檔案：

// .eslintrc.js

module.exports = {
    // ...other config
    noInlineConfig: true,
    reportUnusedDisableDirectives: true
}

以下是扁平化設定中的相同選項：

// eslint.config.js

export default [
    {
        // ...other config
        linterOptions: {
            noInlineConfig: true,
            reportUnusedDisableDirectives: "warn"
        }
    }
];

CLI 旗標變更

以下 CLI 標誌不再支援扁平化設定檔案格式：

  • --rulesdir
  • --ext
  • --resolve-plugins-relative-to

標誌 --no-eslintrc 已被 --no-config-lookup 取代。

--rulesdir

--rulesdir 標誌用於從指定的目錄載入其他規則。當使用扁平化設定時，不再支援此功能。你可以改為直接在設定中建立一個包含本地規則的插件，如下所示：

// eslint.config.js
import myRule from "./rules/my-rule.js";

export default [
    {
        // define the plugin
        plugins: {
            local: {
                rules: {
                    "my-rule": myRule
                }
            }
        },

        // configure the rule
        rules: {
            "local/my-rule": ["error"]
        }

    }
];

--ext

當在命令列上傳遞目錄（例如 npx eslint .）時，--ext 標誌用於指定 ESLint 應搜尋的其他檔案擴展名。當使用扁平化設定時，不再支援此功能。相反地，直接在設定中指定你希望 ESLint 搜尋的檔案模式。例如，如果你之前使用 --ext .ts,.tsx，則需要像這樣更新你的設定檔案：

// eslint.config.js
export default [
    {
        files: ["**/*.ts", "**/*.tsx"]

        // any additional configuration for these file types here
    }
];

ESLint 使用設定檔案中的 files 鍵來判斷應該 lint 哪些檔案。

--resolve-plugins-relative-to

--resolve-plugins-relative-to 標誌用於指示你的設定檔案中插件參考應該相對於哪個目錄解析。這是必要的，因為可共享的設定只能解析那些是父套件的 peer dependencies 或 dependencies 的插件。

使用扁平化設定，可共享的設定可以直接指定它們的依賴關係，因此不再需要此標誌。

不再支援 package.json 設定

使用 eslintrc 時，可以使用 package.json 檔案透過 eslintConfig 鍵來設定 ESLint。

使用扁平化設定，不再可以使用 package.json 檔案來設定 ESLint。你需要將你的設定移至單獨的檔案中。

其他變更

以下是從 eslintrc 到扁平化設定檔案格式所做的變更：

  • root 選項不再存在。（扁平化設定檔案的作用就像已設定 root: true。）
  • files 選項不能再是單一字串，它必須是一個陣列。
  • sourceType 選項現在支援新的值 "commonjs"（.eslintrc 也支援它，但從未記錄在文件中）。

扁平組態檔案的 TypeScript 類型

你可以在 GitHub 上的 lib/types 原始碼資料夾中看到扁平化設定檔案格式的 TypeScript 型別。設定陣列中物件的介面稱為 Linter.Config。

你可以在 lib/types/index.d.ts 中檢視型別定義。

Visual Studio Code 支援

vscode-eslint v3.0.10 中新增了對 ESLint v9.x 的支援。

在 v3.0.10 之前的 vscode-eslint 版本中，預設情況下不會啟用新的設定系統。若要啟用對新設定檔案的支援，請編輯你的 .vscode/settings.json 檔案並新增以下內容：

{
  // required in vscode-eslint < v3.0.10 only
  "eslint.experimental.useFlatConfig": true
}

在未來版本的 ESLint 插件中，你將不再需要手動啟用此功能。

延伸閱讀

編輯此頁面
© OpenJS Foundation 和 ESLint 貢獻者，www.openjsf.org。內容根據 MIT 許可證授權。
變更語言