版本

設定檔

您可以將 ESLint 專案設定放在設定檔中。您可以包含內建規則、您希望如何強制執行這些規則、具有自訂規則的外掛程式、可分享的設定、您希望規則套用至哪些檔案等等。

設定檔

ESLint 設定檔的名稱可以是下列任何一個

它應該放在您專案的根目錄中，並匯出一個設定物件陣列。以下是一個範例

// eslint.config.js
export default [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];

在此範例中，設定陣列只包含一個設定物件。設定物件啟用兩個規則：semi 和 prefer-const。這些規則會套用至 ESLint 使用此設定檔處理的所有檔案。

如果您的專案在其 package.json 檔案中沒有指定 "type":"module"，則 eslint.config.js 必須採用 CommonJS 格式，例如

// eslint.config.js
module.exports = [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];

設定物件

每個設定物件都包含 ESLint 在一組檔案上執行所需的所有資訊。每個設定物件都由這些屬性組成

  • name - 設定物件的名稱。此名稱用於錯誤訊息和設定檢查器中，以協助識別正在使用哪個設定物件。(請參閱命名慣例)
  • files - 一個 glob 模式陣列，指示設定物件應套用至哪些檔案。如果未指定，則設定物件會套用至任何其他設定物件比對的所有檔案。
  • ignores - 一個 glob 模式陣列，指示設定物件不應套用至哪些檔案。如果未指定，則設定物件會套用至 files 比對的所有檔案。如果 ignores 在設定物件中沒有任何其他索引鍵的情況下使用，則這些模式會作為全域忽略。
  • languageOptions - 一個包含與如何為程式碼檢查設定 JavaScript 相關的設定物件。
    • ecmaVersion - 要支援的 ECMAScript 版本。可以是任何年份 (例如，2022) 或版本 (例如，5)。設定為 "latest" 表示最近支援的版本。(預設值："latest")
    • sourceType - JavaScript 原始程式碼的類型。可能的值為傳統腳本檔案的 "script"、ECMAScript 模組 (ESM) 的 "module" 和 CommonJS 檔案的 "commonjs"。(預設值：.js 和 .mjs 檔案的 "module"；.cjs 檔案的 "commonjs")
    • globals - 一個指定在程式碼檢查期間應新增至全域範圍的其他物件的物件。
    • parser - 一個包含 parse() 方法或 parseForESLint() 方法的物件。(預設值：espree)
    • parserOptions - 一個指定直接傳遞至解析器上的 parse() 或 parseForESLint() 方法的其他選項的物件。可用的選項取決於解析器。
  • linterOptions - 一個包含與程式碼檢查過程相關的設定物件。
    • noInlineConfig - 一個布林值，指示是否允許內嵌設定。
    • reportUnusedDisableDirectives - 一個嚴重性字串，指示是否應追蹤和回報未使用的停用和啟用指示詞，以及如何追蹤和回報。為了實現舊版相容性，true 等同於 "warn"，而 false 等同於 "off"。(預設值："warn")。
  • processor - 一個包含 preprocess() 和 postprocess() 方法的物件，或一個指示外掛程式中處理器名稱的字串 (例如，"pluginName/processorName")。
  • plugins - 一個包含外掛程式名稱到外掛程式物件的名稱值對應的物件。指定 files 時，這些外掛程式僅適用於相符的檔案。
  • rules - 一個包含已設定規則的物件。指定 files 或 ignores 時，這些規則設定僅適用於相符的檔案。
  • settings - 一個包含應提供給所有規則使用的資訊的名稱值對物件。

指定 files 和 ignores

您可以使用 files 和 ignores 的組合來決定設定物件應套用至哪些檔案，以及不應套用至哪些檔案。預設情況下，ESLint 會檢查符合 **/*.js、**/*.cjs 和 **/*.mjs 模式的檔案。除非您使用全域忽略明確排除這些檔案，否則這些檔案始終會比對。由於未指定 files 或 ignores 的設定物件會套用至任何其他設定物件比對的所有檔案，因此它們將會套用至所有 JavaScript 檔案。例如

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];

使用此設定，semi 規則會針對 ESLint 中符合預設檔案的所有檔案啟用。因此，如果您將 example.js 傳遞給 ESLint，則會套用 semi 規則。如果您傳遞非 JavaScript 檔案 (例如 example.txt)，則不會套用 semi 規則，因為沒有其他設定物件符合該檔案名稱。(ESLint 會輸出錯誤訊息，讓您知道由於缺少設定而忽略了該檔案。)

使用 ignores 排除檔案

您可以透過指定 files 和 ignores 模式的組合來限制設定物件套用至哪些檔案。例如，您可能希望某些規則僅套用至您 src 目錄中的檔案

// eslint.config.js
export default [
    {
        files: ["src/**/*.js"],
        rules: {
            semi: "error"
        }
    }
];

在這裡，只有 src 目錄中的 JavaScript 檔案會套用 semi 規則。如果您在其他目錄中的檔案上執行 ESLint，則會略過此設定物件。透過新增 ignores，您也可以從此設定物件中移除 src 中的某些檔案

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];

此設定物件比對 src 目錄中的所有 JavaScript 檔案，但以 .config.js 結尾的檔案除外。您也可以在 ignores 中使用否定模式，從忽略模式中排除檔案，例如

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js", "!**/eslint.config.js"],
        rules: {
            semi: "error"
        }
    }
];

在這裡，設定物件會排除以 .config.js 結尾的檔案，但 eslint.config.js 除外。該檔案仍然套用了 semi。

非全域 ignores 模式只能比對檔案名稱。類似 "dir-to-exclude/" 的模式將不會忽略任何內容。若要忽略特定目錄中的所有內容，應改用類似 "dir-to-exclude/**" 的模式。

如果 ignores 在沒有 files 的情況下使用，並且有其他索引鍵 (例如 rules)，則設定物件會套用至除 ignores 排除的檔案之外的所有程式碼檢查檔案，例如

export default [
    {
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];

此配置物件適用於所有 JavaScript 檔案，但以 .config.js 結尾的檔案除外。實際上，這就像將 files 設定為 **/*。一般來說，如果您要指定 ignores，最好總是包含 files。

請注意，當未指定 files 時，取反的 ignores 模式不會導致任何符合條件的檔案自動進行 lint。ESLint 只會對預設匹配或由非 * 且不以 /* 或 /** 結尾的 files 模式匹配的檔案進行 lint。

指定具有任意副檔名的檔案

若要對預設的 .js、.cjs 和 .mjs 以外的副檔名檔案進行 lint，請將它們以 "**/*.extension" 格式的模式包含在 files 中。除了 * 或以 /* 或 /** 結尾的模式之外，任何模式都有效。例如，若要對副檔名為 .ts、.cts 和 .mts 的 TypeScript 檔案進行 lint，您應該指定如下的配置物件：

// eslint.config.js
export default [
    {
        files: [
            "**/*.ts",
            "**/*.cts",
            "**.*.mts"
        ]
    },
    // ...other config
];

指定不帶副檔名的檔案

不帶副檔名的檔案可以使用 !(*.*) 模式進行匹配。例如：

// eslint.config.js
export default [
    {
        files: ["**/!(*.*)"]
    },
    // ...other config
];

以上配置會對所有目錄中，除了預設的 .js、.cjs 和 .mjs 副檔名之外的不帶副檔名的檔案進行 lint。

使用 ignores 全域忽略檔案

如果 ignores 在配置物件中沒有其他鍵一起使用，則這些模式會作為全域忽略項。以下是一個範例：

// eslint.config.js
export default [
    {
        ignores: [".config/*"]
    }
];

此配置指定應該忽略 .config 目錄中的所有檔案。此模式會在預設模式 ["**/node_modules/", ".git/"] 之後添加。

有關配置規則的更多資訊，請參閱忽略檔案。

級聯設定物件

當多個配置物件匹配給定的檔案名稱時，配置物件會合併，後面的物件會在發生衝突時覆寫先前的物件。例如：

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            globals: {
                MY_CUSTOM_GLOBAL: "readonly"
            }
        }
    },
    {
        files: ["tests/**/*.js"],
        languageOptions: {
            globals: {
                it: "readonly",
                describe: "readonly"
            }
        }
    }
];

使用此配置，所有 JavaScript 檔案都會定義一個名為 MY_CUSTOM_GLOBAL 的自訂全域物件，而 tests 目錄中的 JavaScript 檔案除了 MY_CUSTOM_GLOBAL 之外，還將 it 和 describe 定義為全域物件。對於 tests 目錄中的任何 JavaScript 檔案，這兩個配置物件都會被套用，因此 languageOptions.globals 會合併以產生最終結果。

設定程式碼檢查器選項

可以使用 linterOptions 物件來設定特定於 lint 過程的選項。這些選項會影響 lint 的進行方式，而不會影響檔案原始碼的解讀方式。

停用內嵌設定

內嵌配置是使用 /*eslint*/ 註解來實作的，例如 /*eslint semi: error*/。您可以將 noInlineConfig 設定為 true 來禁止內嵌配置。啟用後，所有內嵌配置都會被忽略。以下是一個範例：

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            noInlineConfig: true
        }
    }
];

回報未使用的停用指示詞

停用和啟用指令（例如 /*eslint-disable*/、/*eslint-enable*/ 和 /*eslint-disable-next-line*/）用於停用程式碼某些部分的 ESLint 規則。隨著程式碼的變更，這些指令可能不再需要，因為程式碼的變更方式使得該規則不再被觸發。您可以將 reportUnusedDisableDirectives 選項設定為嚴重性字串，以啟用報告這些未使用的停用指令，如下例所示：

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
];

此設定預設為 "warn"。

您可以使用--report-unused-disable-directives 或 --report-unused-disable-directives-severity 命令列選項來覆寫此設定。

為了與舊版相容，true 等同於 "warn"，false 等同於 "off"。

設定規則

您可以在配置物件中設定任意數量的規則，方法是新增一個包含規則設定的物件的 rules 屬性。此物件中的名稱是規則的名稱，值是每個規則的設定。以下是一個範例：

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];

此配置物件指定應啟用 semi 規則，嚴重性為 "error"。您也可以透過指定一個陣列來為規則提供選項，其中第一個項目是嚴重性，之後的每個項目都是規則的選項。例如，您可以將 semi 規則切換為禁止使用分號，方法是傳遞 "never" 作為選項：

// eslint.config.js
export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    }
];

每個規則都會指定自己的選項，並且可以是任何有效的 JSON 資料類型。請檢查您要設定的規則的文件，以獲取有關其可用選項的更多資訊。

有關配置規則的更多資訊，請參閱配置規則。

設定共用設定

ESLint 支援將共用設定新增至設定檔中。當您將 settings 物件新增至配置物件時，它會被提供給每個規則。依照慣例，外掛程式會將它們感興趣的設定命名空間化，以避免與其他外掛程式衝突。外掛程式可以使用 settings 來指定應該在其所有規則之間共用的資訊。如果您要新增自訂規則並希望它們能夠存取相同的資訊，這可能會很有用。以下是一個範例：

// eslint.config.js
export default [
    {
        settings: {
            sharedData: "Hello"
        },
        plugins: {
            customPlugin: {
                rules: {
                    "my-rule": {
                        meta: {
                            // custom rule's meta information
                        },
                        create(context) {
                            const sharedData = context.settings.sharedData;
                            return {
                                // code
                            };
                        }
                    }
                }
            }
        },
        rules: {
            "customPlugin/my-rule": "error"
        }
    }
];

使用預先定義的設定

ESLint 具有兩個 JavaScript 的預先定義配置：

  • js.configs.recommended - 啟用 ESLint 建議所有人使用的規則，以避免潛在錯誤
  • js.configs.all - 啟用 ESLint 隨附的所有規則

若要包含這些預先定義的配置，請安裝 @eslint/js 套件，然後對後續配置物件中的其他屬性進行任何修改

// eslint.config.js
import js from "@eslint/js";

export default [
    js.configs.recommended,
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

在此，首先會套用 js.configs.recommended 預先定義的配置，然後另一個配置物件會為 no-unused-vars 新增所需的配置。

有關如何將預先定義的配置與您的偏好設定結合使用的更多資訊，請參閱組合配置。

設定命名慣例

name 屬性是可選的，但建議為每個配置物件提供一個名稱，尤其是在您建立共用配置時。該名稱用於錯誤訊息和配置檢查器，以協助識別正在使用的配置物件。

名稱應該描述配置物件的用途，並使用 / 作為分隔符號，使用配置名稱或外掛程式名稱來設定範圍。ESLint 不會在執行時強制名稱必須是唯一的，但建議設定唯一的名稱以避免混淆。

例如，如果您要為名為 eslint-plugin-example 的外掛程式建立配置物件，則可能會將 name 新增至配置物件，並使用 example/ 前綴：

export default {
    configs: {
        recommended: {
            name: "example/recommended",
            rules: {
                "no-unused-vars": "warn"
            }
        },
        strict: {
            name: "example/strict",
            rules: {
                "no-unused-vars": "error"
            }
        }
    }
};

在公開配置物件陣列時，name 可能會有額外的範圍層級，以協助識別配置物件。例如：

export default {
    configs: {
        strict: [
            {
                name: "example/strict/language-setup",
                languageOptions: {
                    ecmaVersion: 2024
                }
            },
            {
                name: "example/strict/sub-config",
                file: ["src/**/*.js"],
                rules: {
                    "no-unused-vars": "error"
                }
            }
        ]
    }
}

使用可分享的設定套件

可共用的配置是一個 npm 套件，它會匯出配置物件或陣列。此套件應該作為您專案中的相依性安裝，然後從您的 eslint.config.js 檔案內部引用。例如，若要使用名為 eslint-config-example 的可共用配置，您的設定檔會如下所示：

// eslint.config.js
import exampleConfig from "eslint-config-example";

export default [
    exampleConfig,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

在此範例中，exampleConfig 是一個物件，因此您可以將其直接插入配置陣列中。

有些可共用的配置會改為匯出陣列，在這種情況下，您需要使用展開運算子將這些項目插入配置陣列中。例如：

// eslint.config.js
import exampleConfigs from "eslint-config-example";

export default [
    ...exampleConfigs,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

請參閱您正在使用的可共用配置套件的文件，以確定它是否正在匯出物件或陣列。

有關如何將可共用的配置與您的偏好設定結合使用的更多資訊，請參閱組合配置。

設定檔解析

當 ESLint 在命令列上執行時，它會先檢查目前的工作目錄是否有 eslint.config.js。如果找到該檔案，則搜尋會停止，否則它會檢查是否有 eslint.config.mjs。如果找到該檔案，則搜尋會停止，否則它會檢查是否有 eslint.config.cjs。如果找不到任何檔案，它會檢查父目錄是否有每個檔案。此搜尋會持續進行，直到找到設定檔或到達根目錄為止。

您可以透過在命令列上使用 -c 或 --config 選項來指定替代設定檔，來防止此對 eslint.config.js 的搜尋，例如：

npx eslint --config some-other-file.js **/*.js

在這種情況下，ESLint 不會搜尋 eslint.config.js，而是改為使用 some-other-file.js。

實驗性設定檔解析

您可以使用 unstable_config_lookup_from_file 標誌來變更 ESLint 搜尋設定檔的方式。ESLint 不會從目前的工作目錄搜尋，而是會從要進行 lint 的檔案目錄開始，然後向上搜尋其祖先目錄，直到找到 eslint.config.js 檔案（或任何其他副檔名的設定檔）。此行為更適合用於 monorepo，其中每個子目錄可能都有自己的設定檔。

若要在命令列上使用此功能，請使用 --flag 標誌：

npx eslint --flag unstable_config_lookup_from_file .

有關使用功能標誌的更多資訊，請參閱功能標誌。

TypeScript 設定檔

您需要透過 unstable_ts_config 功能標誌啟用此功能

npx eslint --flag unstable_ts_config

有關使用功能標誌的更多資訊，請參閱功能標誌。

對於 Deno 和 Bun，原生支援 TypeScript 設定檔；對於 Node.js，您必須在您的專案中安裝可選的開發相依性 jiti 2.0.0 或更新版本（此相依性不會由 ESLint 自動安裝）

npm install -D jiti
# or
yarn add --dev jiti
# or
pnpm add -D jiti

然後，您可以建立具有 .ts、.mts 或 .cts 副檔名的設定檔，並匯出配置物件的陣列。以下是一個 ESM 格式的範例：

import js from "@eslint/js";
import type { Linter } from "eslint";

export default [
  js.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
] satisfies Linter.Config[];

以下是一個 CommonJS 格式的範例：

import type { Linter } from "eslint";
const eslint = require("@eslint/js");

const config: Linter.Config[] = [
  eslint.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
];

module.exports = config;

設定檔優先順序

如果您有多個 ESLint 設定檔，則 ESLint 會優先處理 JavaScript 檔案而不是 TypeScript 檔案。優先順序如下：

  1. eslint.config.js
  2. eslint.config.mjs
  3. eslint.config.cjs
  4. eslint.config.ts
  5. eslint.config.mts
  6. eslint.config.cts

若要覆寫此行為，請使用 --config 或 -c 命令列選項來指定不同的設定檔：

npx eslint --flag unstable_ts_config --config eslint.config.ts
編輯此頁面
© OpenJS Foundation 和 ESLint 貢獻者，www.openjsf.org。內容依據 MIT 授權授權。
變更語言