Configuration 遷移指南

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

要了解更多關於 flat config 格式的資訊，請參考這篇部落格文章。

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

遷移您的設定檔

若要開始使用，請在您現有的 Configuration 檔（.eslintrc、.eslintrc.json、.eslintrc.yml）上使用Configuration 遷移工具，如下所示

npm

npx  @eslint/migrate-config .eslintrc.json 
1

yarn

yarn dlx  @eslint/migrate-config .eslintrc.json 
1

pnpm

pnpm dlx  @eslint/migrate-config .eslintrc.json 
1

bun

bunx  @eslint/migrate-config .eslintrc.json 
1

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

開始使用 Flat Config 檔案

自 ESLint v9.0.0 以來，flat config 檔案格式一直是預設的 Configuration 檔案格式。您可以開始使用 flat config 檔案格式，而無需任何額外的 Configuration。

若要在 ESLint v8 中使用 flat config，請將 eslint.config.js 檔案放在專案的根目錄或將 ESLINT_USE_FLAT_CONFIG 環境變數設定為 true。

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

雖然 Configuration 檔案格式已從 eslintrc 變更為 flat config，但以下內容保持不變

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

Configuration 格式之間的主要差異

eslintrc 和 flat config 格式之間最顯著的一些差異如下

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

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

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

例如，這個 eslintrc Configuration 檔案載入 eslint-plugin-jsdoc 並設定來自該外掛程式的規則

// .eslintrc.js

module.exports = {
    // ...other config
    plugins: ["jsdoc"],
    rules: {
        "jsdoc/require-description": "error",
        "jsdoc/check-values": "error"
    }
    // ...other config
};
1
2
3
4
5
6
7
8
9
10
11

在 flat 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"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

自訂解析器

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

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

例如，這個 eslintrc Configuration 檔案使用 @babel/eslint-parser 解析器

// .eslintrc.js

module.exports = {
    // ...other config
    parser: "@babel/eslint-parser",
    // ...other config
};
1
2
3
4
5
6
7

在 flat config 中，您會像這樣做同樣的事情

// eslint.config.js

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

export default [
    {
        // ...other config
        languageOptions: {
            parser: babelParser
        }
        // ...other config
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13

處理器

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

在 flat config 檔案中，處理器仍然可以從外掛程式依其名稱引用，但現在也可以直接插入 Configuration 中。處理器永遠不會自動設定，並且必須在 Configuration 中明確設定。

以具有處理器的自訂外掛程式為例

// node_modules/eslint-plugin-someplugin/index.js
module.exports = {
    processors: {
        ".md": {
            preprocess() {},
            postprocess() {}
        },
        "someProcessor": {
            preprocess() {},
            postprocess() {}
        }
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13

在 eslintrc 中，您會如下設定

// .eslintrc.js
module.exports = {
    plugins: ["someplugin"],
    processor: "someplugin/someProcessor"
};
1
2
3
4
5

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

{
     overrides: [{
        files: ["**/*.md"],
        processor: "someplugin/.md"
     }]
}
1
2
3
4
5
6

在 flat config 中，以下都是表達相同內容的有效方式

// 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
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

請注意，由於 .md 處理器不是由 flat config 自動新增的，因此您也需要指定一個額外的 Configuration 元素

{
    files: ["**/*.md"],
    processor: somePlugin.processors[".md"]
}
1
2
3
4

基於 Glob 的設定

預設情況下，eslintrc 檔案會檢查它們所在的目錄及其子目錄中的所有檔案（.eslintignore 涵蓋的檔案除外）。如果您想要針對不同的檔案 glob 模式使用不同的 Configuration，您可以在 overrides 屬性中指定它們。

預設情況下，flat config 檔案在匯出的陣列中支援不同的基於 glob 模式的設定。您可以將 glob 模式包含在 Configuration 物件的 files 屬性中。如果您未指定 files 屬性，則 Configuration 預設為 glob 模式 "**/*.{js,mjs,cjs}"。基本上，flat config 檔案中的所有 Configuration 都像 eslintrc overrides 屬性。

eslintrc 範例

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

// .eslintrc.js

module.exports = {
    // ...other config
    rules: {
        semi: ["warn", "always"]
    }
};
1
2
3
4
5
6
7
8

這個 eslintrc 檔案支援具有 overrides 的多個 Configuration

// .eslintrc.js

module.exports = {
    // ...other config
    overrides: [
        {
            files: ["src/**/*"],
            rules: {
                semi: ["warn", "always"]
            }
        },
        {
            files:["test/**/*"],
            rules: {
                "no-console": "off"
            }
        }
    ]
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

對於 flat config，以下是具有預設 glob 模式的 Configuration

// 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
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

支援不同 glob 模式的多個 Configuration 的 flat config 範例 Configuration

// 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
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

設定語言選項

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

在 flat config 檔案中，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
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

這是 flat config 中的相同 Configuration

// eslint.config.js

import globals from "globals";

export default [
    {
        languageOptions: {
            ecmaVersion: 2022,
            sourceType: "module",
            globals: {
                ...globals.browser,
                ...globals.node,
                myCustomGlobal: "readonly"
            }
        }
        // ...other config
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

`eslint-env` Configuration 註解

在 eslintrc Configuration 系統中，可以使用 eslint-env Configuration 註解來定義檔案的全域變數。當使用 flat config 進行檢查時，不再識別這些註解：在未來版本的 ESLint 中，eslint-env 註解將被回報為錯誤。因此，從 eslintrc 遷移到 flat config 時，應從所有檔案中移除 eslint-env Configuration 註解。它們可以替換為等效但更詳細的 global Configuration 註解，或在 Configuration 檔中刪除以支持 globals 定義。

例如，當使用 eslintrc 時，要檢查的檔案可能看起來像這樣

// tests/my-file.js

/* eslint-env mocha */

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});
1
2
3
4
5
6
7
8
9

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

使用 global Configuration 註解的 flat config 可以實現相同的效果，例如

// tests/my-file.js

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

describe("unit tests", () => {
    it("should pass", () => {
        // ...
    });
});
1
2
3
4
5
6
7
8
9

另一個選項是從要檢查的檔案中移除註解，並在 Configuration 中定義全域變數，例如

// eslint.config.js

import globals from "globals";

export default [
    // ...other config
    {
        files: [
            "tests/**"
        ],
        languageOptions: {
            globals: {
                ...globals.mocha
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

預定義和可分享的設定

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

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

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

在 flat config 檔案中，預定義的設定從單獨的模組匯入到 flat config 檔案中。recommended 和 all 規則設定位於 @eslint/js 套件中。您必須匯入此套件才能使用這些設定

npm

npm install --save-dev @eslint/js
1

yarn

yarn add --dev @eslint/js
1

pnpm

pnpm add --save-dev @eslint/js
1

bun

bun add --dev @eslint/js
1

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

例如，這是使用內建 eslint:recommended 設定的 eslintrc 檔案

// .eslintrc.js

module.exports = {
    // ...other config
    extends: "eslint:recommended",
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}
1
2
3
4
5
6
7
8
9
10

這個 eslintrc 檔案使用內建設定、本機自訂設定和來自 npm 套件的可分享設定

// .eslintrc.js

module.exports = {
    // ...other config
    extends: ["eslint:recommended", "./custom-config.js", "eslint-config-my-config"],
    rules: {
        semi: ["warn", "always"]
    },
    // ...other config
}
1
2
3
4
5
6
7
8
9
10

若要在 flat 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
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

請注意，由於您只是匯入 JavaScript 模組，因此您可以在 ESLint 使用它們之前變更 Configuration 物件。例如，您可能希望讓特定的 Configuration 物件僅適用於您的測試檔案

// eslint.config.js

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

export default [
    js.configs.recommended,
    {
        ...customTestConfig,
        files: ["**/*.test.js"],
    },
];
1
2
3
4
5
6
7
8
9
10
11
12

在 Flat Config 中使用 eslintrc 設定

您可能會發現您依賴的可分享設定尚未更新為 flat config 格式。在這種情況下，您可以使用 FlatCompat 工具將 eslintrc 格式轉換為 flat config 格式。首先，安裝 @eslint/eslintrc 套件

npm

npm install --save-dev @eslint/eslintrc
1

yarn

yarn add --dev @eslint/eslintrc
1

pnpm

pnpm add --save-dev @eslint/eslintrc
1

bun

bun add --dev @eslint/eslintrc
1

然後，匯入 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"),
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

此範例使用 FlatCompat#extends() 方法將 eslint-config-my-config 插入到 flat config 陣列中。

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

忽略檔案

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

若要使用 flat config 忽略檔案，您可以在沒有其他屬性的 Configuration 物件中使用 ignores 屬性。ignores 屬性接受 glob 模式陣列。Flat config 不支援從 .eslintignore 檔案載入忽略模式，因此您需要將這些模式直接遷移到 flat config 中。

例如，以下是您可以與 eslintrc 設定一起使用的 .eslintignore 範例

# .eslintignore
temp.js
config/*
# ...other ignored files
1
2
3
4

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

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

flat config 中等效的忽略模式如下所示

export default [
    // ...other config
    {
        // Note: there should be no other properties in this object
        ignores: ["**/temp.js", "config/*"]
    }
];
1
2
3
4
5
6
7

在 .eslintignore 中，temp.js 會忽略所有名為 temp.js 的檔案，而在 flat config 中，您需要將其指定為 **/temp.js。flat config 中的模式 temp.js 僅忽略與 Configuration 檔案位於同一目錄中的名為 temp.js 的檔案。

Linter 選項

Eslintrc 檔案可讓您使用 noInlineConfig 和 reportUnusedDisableDirectives 屬性來設定 linter 本身。

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

例如，以下是啟用 linter 選項的 eslintrc 檔案

// .eslintrc.js

module.exports = {
    // ...other config
    noInlineConfig: true,
    reportUnusedDisableDirectives: true
}
1
2
3
4
5
6
7

以下是 flat config 中的相同選項

// eslint.config.js

export default [
    {
        // ...other config
        linterOptions: {
            noInlineConfig: true,
            reportUnusedDisableDirectives: "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11

CLI 標誌變更

以下 CLI 標誌不再受 flat config 檔案格式支援

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

標誌 --no-eslintrc 已替換為 --no-config-lookup。

`--rulesdir`

--rulesdir 標誌用於從指定的目錄載入其他規則。使用 flat config 時不再支援此功能。您可以改為建立一個包含您直接在 Configuration 中的本機規則的外掛程式，如下所示

// 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"]
        }

    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

`--ext`

--ext 標誌用於指定當在命令列上傳遞目錄（例如 npx eslint .）時，ESLint 應搜尋的其他檔案副檔名。使用 flat config 時不再支援此功能。相反，直接在您的 Configuration 中指定您想要 ESLint 搜尋的檔案模式。例如，如果您之前使用 --ext .ts,.tsx，則您需要像這樣更新您的 Configuration 檔案

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

        // any additional configuration for these file types here
    }
];
1
2
3
4
5
6
7
8

ESLint 使用 Configuration 檔案中的 files 鍵來判斷應檢查哪些檔案。

`--resolve-plugins-relative-to`

--resolve-plugins-relative-to 標誌用於指示 Configuration 檔案中的外掛程式參考應相對於哪個目錄解析。這是必要的，因為可分享的設定只能解析作為同層級相依性或父套件相依性的外掛程式。

使用 flat config，可分享的設定可以直接指定它們的相依性，因此不再需要此標誌。

不再支援 `package.json` Configuration

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

使用 flat config，不再可以使用 package.json 檔案來設定 ESLint。您需要將您的 Configuration 移至單獨的檔案中。

其他變更

以下變更已從 eslintrc 變更為 flat config 檔案格式

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

Flat Config 檔案的 TypeScript 類型

您可以在 GitHub 上的 lib/types 原始程式碼資料夾中查看 flat config 檔案格式的 TypeScript 類型。Configuration 陣列中物件的介面稱為 Linter.Config。

您可以在 lib/types/index.d.ts 中查看類型定義。

Visual Studio Code 支援

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

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

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

在未來版本的 ESLint 外掛程式中，您將不再需要手動啟用此功能。

延伸閱讀

編輯此頁面

Configuration 遷移指南

遷移您的設定檔

npm

yarn

pnpm

bun

開始使用 Flat Config 檔案

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

Configuration 格式之間的主要差異

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

自訂解析器

處理器

基於 Glob 的設定

eslintrc 範例

設定語言選項

eslint-env Configuration 註解

預定義和可分享的設定

npm

yarn

pnpm

bun

在 Flat Config 中使用 eslintrc 設定

npm

yarn

pnpm

bun

忽略檔案

Linter 選項

CLI 標誌變更

--rulesdir

--ext

--resolve-plugins-relative-to

不再支援 package.json Configuration

其他變更

Flat Config 檔案的 TypeScript 類型

Visual Studio Code 支援

延伸閱讀

`eslint-env` Configuration 註解

`--rulesdir`

`--ext`

`--resolve-plugins-relative-to`

不再支援 `package.json` Configuration