版本

設定檔

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

設定檔

ESLint 設定檔可以命名為下列任何一個

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
]);

在此範例中，defineConfig() 輔助函式用於定義只有一個設定物件的設定陣列。設定物件啟用兩個規則：semi 和 prefer-const。這些規則會套用至 ESLint 使用此設定檔處理的所有檔案。

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

// eslint.config.js
const { defineConfig } = require("eslint/config");

module.exports = defineConfig([
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
]);

設定物件

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

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

指定 files 和 ignores

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        rules: {
            semi: "error"
        }
    }
]);

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

使用 ignores 排除檔案

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["src/**/*.js"],
        rules: {
            semi: "error"
        }
    }
]);

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

import { defineConfig } from "eslint/config";

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

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

import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        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)，則設定物件會套用至所有 linted 檔案，但 ignores 排除的檔案除外，例如

import { defineConfig } from "eslint/config";

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

此設定物件會套用至所有 JavaScript 檔案，但以 .config.js 結尾的檔案除外。實際上，這就像將 files 設定為 **/*。一般而言，如果您要指定 ignores，最好始終包含 files。

請注意，當未指定 files 時，否定的 ignores 模式不會導致自動 lint 任何相符的檔案。ESLint 僅 lint 預設比對或 files 模式比對的檔案，且該模式不是 * 且不以 /* 或 /** 結尾。

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: [
            "**/*.ts",
            "**/*.cts",
            "**.*.mts"
        ]
    },
    // ...other config
]);

指定沒有副檔名的檔案

沒有副檔名的檔案可以使用模式 !(*.*) 比對。例如

// eslint.config.js
import { defineConfig } from "eslint/config";

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

上述設定會 lint 所有目錄中沒有副檔名的檔案，但預設 .js、.cjs 和 .mjs 副檔名除外。

使用 ignores 全域忽略檔案

根據 ignores 屬性的使用方式，它可以表現為非全域 ignores 或全域 ignores。

  • 當 ignores 在設定物件中未使用任何其他索引鍵 (除了 name) 時，這些模式會作為全域忽略。這表示它們會套用至每個設定物件 (而不僅僅是定義它的設定物件)。全域 ignores 可讓您不必在多個設定物件中複製和保持 ignores 屬性同步。
  • 如果 ignores 與同一設定物件中的其他屬性一起使用，則這些模式會作為非全域忽略。這樣，ignores 僅適用於定義它的設定物件。

全域和非全域 ignores 有一些使用上的差異

  • 非全域 ignores 中的模式僅比對檔案 (dir/filename.js) 或目錄中的檔案 (dir/**)
  • 全域 ignores 中的模式可以比對目錄 (dir/)，以及非全域忽略支援的模式。

對於所有 ignores 的使用

  • 您定義的模式會新增在預設 ESLint 模式 (即 ["**/node_modules/", ".git/"]) 之後。
  • 這些模式永遠比對以點開頭的檔案和目錄，例如 .foo.js 或 .fixtures，除非這些檔案被明確忽略。依預設忽略的唯一點目錄是 .git。
// eslint.config.js
import { defineConfig } from "eslint/config";

// Example of global ignores
export default defineConfig([
    {
      ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
    },
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

為了避免混淆，請使用 globalIgnores() 輔助函式來清楚指示哪些忽略是要作為全域忽略。以下是先前範例的重寫版本，使用 globalIgnores()

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

// Example of global ignores
export default defineConfig([
    globalIgnores([".config/", "dist/", "tsconfig.json"]),
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

如需有關設定規則以忽略的更多資訊和範例，請參閱 忽略檔案。

串聯設定物件

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        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 會合併以建立最終結果。

設定 Linter 選項

特定於 linting 流程的選項可以使用 linterOptions 物件進行設定。這些選項會影響 linting 的進行方式，但不會影響檔案原始碼的解譯方式。

停用行內設定

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            noInlineConfig: true
        }
    }
]);

回報未使用的停用指令

停用和啟用指令 (例如 /*eslint-disable*/、/*eslint-enable*/ 和 /*eslint-disable-next-line*/) 用於停用程式碼特定部分周圍的 ESLint 規則。隨著程式碼的變更，這些指令可能不再需要，因為程式碼已變更，使得規則不再觸發。您可以將 reportUnusedDisableDirectives 選項設定為嚴重性字串來啟用回報這些未使用的停用指令，如此範例所示

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
]);

此設定預設為 "warn"。

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

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

回報未使用的行內設定

行內設定註解 (例如 /* eslint rule-name: "error" */) 用於變更程式碼特定部分周圍的 ESLint 規則嚴重性和/或選項。隨著專案的 ESLint 設定檔變更，這些指令可能不再與已設定的內容有所不同。您可以將 reportUnusedInlineConfigs 選項設定為嚴重性字串來啟用回報這些未使用的行內設定註解，如此範例所示

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedInlineConfigs: "error"
        }
    }
]);

您可以使用 --report-unused-inline-configs 命令列選項來覆寫此設定。

設定規則

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        rules: {
            semi: "error"
        }
    }
]);

此設定物件指定 semi 規則應以 "error" 的嚴重性啟用。您也可以透過指定陣列來為規則提供選項，其中第一個項目是嚴重性，而其後的每個項目都是規則的選項。例如，您可以透過傳遞 "never" 作為選項，將 semi 規則切換為不允許分號

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        rules: {
            semi: ["error", "never"]
        }
    }
]);

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

如需有關設定規則的更多資訊，請參閱 設定規則。

設定共用設定

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        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"
        }
    }
]);

擴充設定

設定物件使用 extends 來繼承另一個設定物件或陣列的所有特性 (包括規則、外掛程式和語言選項)，然後可以修改所有選項。extends 索引鍵是一個值陣列，指示要從哪些設定擴充。extends 陣列的元素可以是以下三個值之一

  • 指定外掛程式中設定名稱的字串
  • 設定物件
  • 設定陣列

使用來自外掛程式的設定

ESLint 外掛程式可以匯出預先定義的設定。這些設定使用字串參考，並遵循 pluginName/configName 模式。外掛程式必須先在 plugins 索引鍵中指定。以下是一個範例

// eslint.config.js
import examplePlugin from "eslint-plugin-example";
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        plugins: {
            example: examplePlugin
        },
        extends: ["example/recommended"]
    }
]);

在此範例中，會載入來自 eslint-plugin-example 的名為 recommended 的設定。外掛程式設定也可以在設定陣列內依名稱參考。

您也可以將外掛程式設定直接插入 extends 陣列中。例如

// eslint.config.js
import pluginExample from "eslint-plugin-example";
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        plugins: {
            example: pluginExample
        },
        extends: [pluginExample.configs.recommended]
    }
]);

在此情況下，名為 recommended 的設定會直接透過外掛程式物件的 configs 屬性存取。

使用預先定義的設定

ESLint 有兩個 JavaScript 的預先定義設定

  • js/recommended - 啟用 ESLint 建議所有人使用的規則，以避免潛在錯誤。
  • js/all - 啟用 ESLint 隨附的所有規則。不建議在生產環境中使用此設定，因為它會隨著 ESLint 的每個次要版本和主要版本而變更。使用風險自負。

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

// eslint.config.js
import js from "@eslint/js";
import { defineConfig } from "eslint/config";

export default defineConfig([
    {
        plugins: {
            js
        },
        extends: ["js/recommended"],
        rules: {
            "no-unused-vars": "warn"
        }
    }
]);

在這裡，會先套用 js/recommended 預先定義的設定，然後另一個設定物件會新增 no-unused-vars 的所需設定。

如需有關如何將預先定義的設定與您的偏好設定結合的更多資訊，請參閱 合併設定。

使用可分享的設定套件

可分享的設定是一個 npm 套件，它匯出設定物件或陣列。此套件應作為您專案中的相依性安裝，然後從您的 eslint.config.js 檔案內參考。例如，若要使用名為 eslint-config-example 的可分享設定，您的設定檔看起來會像這樣

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

export default defineConfig([
    {
        extends: [exampleConfig],
        rules: {
            "no-unused-vars": "warn"
        }
    }
]);

在此範例中，exampleConfig 可以是物件或陣列，無論哪種方式，它都可以直接插入 extends 陣列中。

如需有關如何將可分享的設定與您的偏好設定結合的更多資訊，請參閱 合併設定。

設定命名慣例

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

設定檔解析

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

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

npm

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

yarn

yarn dlx eslint --config some-other-file.js **/*.js

pnpm

pnpm dlx eslint --config some-other-file.js **/*.js

bun

bunx 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 設定檔

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

npm

npm install --save-dev jiti

yarn

yarn add --dev jiti

pnpm

pnpm add --save-dev jiti

bun

bun add --dev jiti

然後，您可以建立副檔名為 .ts、.mts 或 .cts 的設定檔，並匯出 設定物件 的陣列。

設定檔優先順序

如果您有多個 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 命令列選項來指定不同的設定檔

npm

npx eslint --config eslint.config.ts

yarn

yarn dlx eslint --config eslint.config.ts

pnpm

pnpm dlx eslint --config eslint.config.ts

bun

bunx eslint --config eslint.config.ts
編輯此頁面
© OpenJS Foundation 和 ESLint 貢獻者，www.openjsf.org。內容授權條款為 MIT 授權條款。
變更語言