Node.js API 參考

雖然 ESLint 設計為在命令列上執行，但可以透過 Node.js API 以程式設計方式使用 ESLint。Node.js API 的目的是讓外掛程式和工具作者可以直接使用 ESLint 功能，而無需透過命令列介面。

注意：使用 API 中未記錄的部分，風險自負。只有本文檔中明確提及的部分才獲准使用，並且將保持穩定可靠。任何未記錄的部分都是不穩定的，可能隨時更改或刪除。

ESLint 類別

ESLint 類別是在 Node.js 應用程式中使用的主要類別。

此類別依賴 Node.js fs 模組和檔案系統，因此您無法在瀏覽器中使用它。如果您想在瀏覽器上檢查程式碼，請改用 Linter 類別。

以下是使用 ESLint 類別的簡單範例

const { ESLint } = require("eslint");

(async function main() {
    // 1. Create an instance.
    const eslint = new ESLint();

    // 2. Lint files.
    const results = await eslint.lintFiles(["lib/**/*.js"]);

    // 3. Format the results.
    const formatter = await eslint.loadFormatter("stylish");
    const resultText = formatter.format(results);

    // 4. Output it.
    console.log(resultText);
})().catch((error) => {
    process.exitCode = 1;
    console.error(error);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

以下是一個自動修正程式碼檢查問題的範例

const { ESLint } = require("eslint");

(async function main() {
    // 1. Create an instance with the `fix` option.
    const eslint = new ESLint({ fix: true });

    // 2. Lint files. This doesn't modify target files.
    const results = await eslint.lintFiles(["lib/**/*.js"]);

    // 3. Modify the files with the fixed code.
    await ESLint.outputFixes(results);

    // 4. Format the results.
    const formatter = await eslint.loadFormatter("stylish");
    const resultText = formatter.format(results);

    // 5. Output it.
    console.log(resultText);
})().catch((error) => {
    process.exitCode = 1;
    console.error(error);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

以下是如何使用 ESLint 類別和 lintText API 的範例

const { ESLint } = require("eslint");

const testCode = `
  const name = "eslint";
  if(true) {
    console.log("constant condition warning")
  };
`;

(async function main() {
    // 1. Create an instance
    const eslint = new ESLint({
        overrideConfigFile: true,
        overrideConfig: {
            languageOptions: {
                ecmaVersion: 2018,
                sourceType: "commonjs"
            }
        },
    });

    // 2. Lint text.
    const results = await eslint.lintText(testCode);

    // 3. Format the results.
    const formatter = await eslint.loadFormatter("stylish");
    const resultText = formatter.format(results);

    // 4. Output it.
    console.log(resultText);
})().catch((error) => {
    process.exitCode = 1;
    console.error(error);
});
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
26
27
28
29
30
31
32
33
34

◆ new ESLint(options)

const eslint = new ESLint(options);
1

建立新的 ESLint 實例。

參數

ESLint 建構函式採用 options 物件。如果您省略 options 物件，則會對所有選項使用預設值。options 物件具有下列屬性。

檔案列舉

• options.cwd (string)
  預設值為 process.cwd()。工作目錄。這必須是絕對路徑。
• options.errorOnUnmatchedPattern (boolean)
  預設值為 true。除非設定為 false，否則當找不到目標檔案時，eslint.lintFiles() 方法將會擲回錯誤。
• options.globInputPaths (boolean)
  預設值為 true。如果存在 false，則 eslint.lintFiles() 方法不會解譯 glob 模式。
• options.ignore (boolean)
  預設值為 true。如果存在 false，則 eslint.lintFiles() 方法不會遵從您設定中的 ignorePatterns。
• options.ignorePatterns (string[] | null)
  預設值為 null。除了設定忽略之外，要使用的忽略檔案模式。這些模式相對於 cwd。
• options.passOnNoPatterns (boolean)
  預設值為 false。當設定為 true 時，遺失的模式會導致程式碼檢查作業短路，並且不報告任何失敗。
• options.warnIgnored (boolean)
  預設值為 true。當檔案清單包含忽略的檔案時，顯示警告。

程式碼檢查

• options.allowInlineConfig (boolean)
  預設值為 true。如果存在 false，ESLint 會抑制原始程式碼中的指示詞註解。如果此選項為 false，它會覆寫您設定中的 noInlineConfig 設定。
• options.baseConfig (ConfigData | ConfigData[] | null)
  預設值為 null。設定物件，由這個實例使用的所有設定擴充。您可以使用此選項來定義預設設定，如果您的設定檔沒有設定它，則會使用這些設定。
• options.overrideConfig (ConfigData | ConfigData[] | null)
  預設值為 null。設定物件，覆寫此實例使用的所有設定。您可以使用此選項來定義設定，即使您的設定檔設定了它，也會使用這些設定。
• options.overrideConfigFile (string | boolean)
  預設值為 false。設定檔的路徑，會覆寫此實例使用的所有設定。options.overrideConfig 選項會在套用此選項之後套用。
• options.plugins (Record<string, Plugin> | null)
  預設值為 null。ESLint 用於您設定的 plugins 設定的外掛程式實作。這是一個類似 Map 的物件。這些鍵是外掛程式 ID，每個值都是實作。
• options.ruleFilter (({ruleId: string, severity: number}) => boolean)
  預設值為 () => true。一個篩選要執行的規則的述詞函式。此函式會使用包含 ruleId 和 severity 的物件呼叫，如果應該執行規則，則會回傳 true。
• options.stats (boolean)
  預設值為 false。當設定為 true 時，會將額外的統計資料新增至程式碼檢查結果（請參閱 統計資料型別）。

自動修正

• options.fix (boolean | (message: LintMessage) => boolean)
  預設值為 false。如果存在 true，則 eslint.lintFiles() 和 eslint.lintText() 方法會在自動修正模式下運作。如果存在述詞函式，則方法會將每個程式碼檢查訊息傳遞至該函式，然後只使用該函式傳回 true 的程式碼檢查訊息。
• options.fixTypes (("directive" | "problem" | "suggestion" | "layout")[] | null)
  預設值為 null。eslint.lintFiles() 和 eslint.lintText() 方法用於自動修正的規則類型。

快取相關

• options.cache (boolean)
  預設值為 false。如果存在 true，則 eslint.lintFiles() 方法會快取程式碼檢查結果，並且如果每個目標檔案都未變更，則會使用它。請注意，當您升級 ESLint 外掛程式時，ESLint 不會清除快取。在這種情況下，您必須手動移除快取檔案。eslint.lintText() 方法即使您將 options.filePath 傳遞至方法，也不會使用快取。
• options.cacheLocation (string)
  預設值為 .eslintcache。eslint.lintFiles() 方法會將快取寫入此檔案。
• options.cacheStrategy (string)
  預設值為 "metadata"。用於偵測變更檔案的快取策略。可以是 "metadata" 或 "content"。

其他選項

• options.flags (string[])
  預設值為 []。要為此實例啟用的功能旗標。

◆ eslint.lintFiles(patterns)

const results = await eslint.lintFiles(patterns);
1

此方法會檢查符合 glob 模式的檔案，然後回傳結果。

參數

• patterns (string | string[])
  程式碼檢查目標檔案。這可以包含任何檔案路徑、目錄路徑和 glob 模式。

回傳值

• (Promise<LintResult[]>)
  將會使用 LintResult 物件陣列實現的 Promise。

◆ eslint.lintText(code, options)

const results = await eslint.lintText(code, options);
1

此方法會檢查指定的原始程式碼文字，然後回傳結果。

依預設，此方法會使用適用於目前工作目錄 (cwd 建構函式選項) 中檔案的設定。如果您想使用不同的設定，請傳遞 options.filePath，ESLint 會載入 eslint.lintFiles() 會用於 options.filePath 中檔案的相同設定。

如果 options.filePath 值設定為忽略，則此方法會回傳空陣列。如果設定了 options.warnIgnored 選項以及 options.filePath 選項，則此方法會回傳 LintResult 物件。在這種情況下，結果可能包含一個警告，指出該檔案已被忽略。

參數

第二個參數 options 是可省略的。

• code (string)
  要檢查的原始程式碼文字。
• options.filePath (string)
  選用。原始程式碼文字的檔案路徑。如果省略，則 result.filePath 會變成字串 "<text>"。
• options.warnIgnored (boolean)
  選用，預設為傳遞至建構函式的 options.warnIgnored。如果存在 true 且 options.filePath 是 ESLint 應該忽略的檔案，則此方法會回傳包含警告訊息的程式碼檢查結果。

回傳值

• (Promise<LintResult[]>)
  將會使用 LintResult 物件陣列實現的 Promise。這是一個陣列 (儘管只有一個程式碼檢查結果)，以保持此方法與 eslint.lintFiles() 方法之間的介面相似。

◆ eslint.getRulesMetaForResults(results)

const results = await eslint.lintFiles(patterns);
const rulesMeta = eslint.getRulesMetaForResults(results);
1
2

此方法會回傳一個物件，其中包含在給定的 results 中觸發程式碼檢查錯誤的每個規則的中繼資訊。

參數

• results (LintResult[])
  從呼叫 ESLint#lintFiles() 或 ESLint#lintText() 回傳的 LintResult 物件陣列。

回傳值

• (Object)
  一個物件，其屬性名稱是 results 中的規則 ID，其屬性值是規則的中繼資訊（如果有的話）。

◆ eslint.calculateConfigForFile(filePath)

const config = await eslint.calculateConfigForFile(filePath);
1

此方法會計算給定檔案的設定，這對於除錯目的很有用。

參數

• filePath (string)
  要計算設定檔的路徑。禁止使用目錄路徑，因為 ESLint 無法處理 overrides 設定。

回傳值

• (Promise<Object>)
  將會以設定物件完成的 Promise。

◆ eslint.isPathIgnored(filePath)

const isPathIgnored = await eslint.isPathIgnored(filePath);
1

此方法檢查給定的檔案是否被您的設定忽略。

參數

• filePath (string)
  您要檢查的檔案路徑。

回傳值

• (Promise<boolean>)
  將會以檔案是否被忽略的結果完成的 Promise。如果檔案被忽略，則會回傳 true。

◆ eslint.loadFormatter(nameOrPath)

const formatter = await eslint.loadFormatter(nameOrPath);
1

此方法載入格式化工具。格式化工具將程式碼檢查結果轉換為人類或機器可讀的字串。

參數

• nameOrPath (string | undefined)
  您要檢查的檔案路徑。允許以下值：
  • undefined。在這種情況下，會載入內建的 "stylish" 格式化工具。
  • 內建格式化工具的名稱。
  • 第三方格式化工具的名稱。例如：
    • "foo" 將會載入 eslint-formatter-foo。
    • "@foo" 將會載入 @foo/eslint-formatter。
    • "@foo/bar" 將會載入 @foo/eslint-formatter-bar。
  • 定義格式化工具的檔案路徑。該路徑必須包含一個或多個路徑分隔符號 (/)，才能區分它是路徑還是名稱。例如，以 ./ 開頭。

回傳值

• (Promise<LoadedFormatter>)
  將會以 LoadedFormatter 物件完成的 Promise。

◆ eslint.hasFlag(flagName)

此方法用於判斷是否已設定給定的功能標誌，如下例所示：

if (eslint.hasFlag("x_feature")) {
    // handle flag
}
1
2
3

參數

• flagName (string)
  要檢查的標誌。

回傳值

• (boolean)
  如果標誌已啟用，則為 True。

◆ ESLint.version

const version = ESLint.version;
1

ESLint 的版本字串。例如，"7.0.0"。

這是一個靜態屬性。

◆ ESLint.defaultConfig

const defaultConfig = ESLint.defaultConfig;
1

ESLint 內部使用的預設設定。此設定提供給想要使用與 ESLint 相同的預設值計算設定的工具。請記住，預設設定可能會因版本而異，因此您不應該依賴任何特定的鍵或值是否存在。

這是一個靜態屬性。

◆ ESLint.outputFixes(results)

await ESLint.outputFixes(results);
1

此方法將 ESLint 的自動修正功能修改的程式碼寫入其各自的檔案。如果任何修改的檔案不存在，此方法將不會執行任何動作。

這是一個靜態方法。

參數

• results (LintResult[])
  要寫入的 LintResult 物件。

回傳值

• (Promise<void>)
  在所有檔案都寫入後將會完成的 Promise。

◆ ESLint.getErrorResults(results)

const filteredResults = ESLint.getErrorResults(results);
1

此方法複製給定的結果並移除警告。回傳值僅包含錯誤。

這是一個靜態方法。

參數

• results (LintResult[])
  要篩選的 LintResult 物件。

回傳值

• (LintResult[])
  篩選後的 LintResult 物件。

◆ LintResult 型別

LintResult 值是每個檔案的程式碼檢查結果資訊。eslint.lintFiles() 和 eslint.lintText() 方法會回傳它。它具有以下屬性：

• filePath (string)
  此結果的檔案絕對路徑。如果檔案路徑未知（當您未將 options.filePath 選項傳遞給 eslint.lintText() 方法時），則為字串 "<text>"。
• messages (LintMessage[])
  LintMessage 物件的陣列。
• suppressedMessages (SuppressedLintMessage[])
  SuppressedLintMessage 物件的陣列。
• fixableErrorCount (number)
  可由 fix 建構函式選項自動修正的錯誤數量。
• fixableWarningCount (number)
  可由 fix 建構函式選項自動修正的警告數量。
• errorCount (number)
  錯誤數量。這包括可修正的錯誤和嚴重錯誤。
• fatalErrorCount (number)
  嚴重錯誤的數量。
• warningCount (number)
  警告的數量。這包括可修正的警告。
• output (string | undefined)
  修改後的原始碼文字。如果不存在任何可修正的訊息，則此屬性為 undefined。
• source (string | undefined)
  原始原始碼文字。如果不存在任何訊息或存在 output 屬性，則此屬性為 undefined。
• stats (Stats | undefined)
  Stats 物件。這包含使用 stats 選項收集的程式碼檢查效能統計資料。
• usedDeprecatedRules ({ ruleId: string; replacedBy: string[] }[])
  有關用於檢查此檔案的已棄用規則的資訊。

◆ LintMessage 型別

LintMessage 值是每個程式碼檢查錯誤的資訊。LintResult 類型的 messages 屬性包含它。它具有以下屬性：

• ruleId (string | null)
  產生此程式碼檢查訊息的規則名稱。如果此訊息是由 ESLint 核心而非規則產生，則為 null。
• severity (1 | 2)
  此訊息的嚴重性。1 表示警告，而 2 表示錯誤。
• fatal (boolean | undefined)
  如果這是與規則無關的嚴重錯誤，例如剖析錯誤，則為 true。
• message (string)
  錯誤訊息。
• messageId (string | undefined)
  程式碼檢查錯誤的訊息 ID。如果規則未使用訊息 ID，則此屬性為 undefined。
• line (number | undefined)
  此訊息的起始點的以 1 為基礎的行號。
• column (number | undefined)
  此訊息的起始點的以 1 為基礎的欄號。
• endLine (number | undefined)
  此訊息的結束點的以 1 為基礎的行號。如果此訊息不是範圍，則此屬性為 undefined。
• endColumn (number | undefined)
  此訊息的結束點的以 1 為基礎的欄號。如果此訊息不是範圍，則此屬性為 undefined。
• fix (EditInfo | undefined)
  自動修正的 EditInfo 物件。如果此訊息不可修正，則此屬性為 undefined。
• suggestions ({ desc: string; fix: EditInfo; messageId?: string; data?: object }[] | undefined)
  建議清單。每個建議都是描述和 EditInfo 物件的配對，用於修正程式碼。API 使用者（例如編輯器整合）可以選擇其中一個來修正此訊息的問題。如果此訊息沒有任何建議，則此屬性為 undefined。

◆ SuppressedLintMessage 型別

SuppressedLintMessage 值是每個被抑制的程式碼檢查錯誤的資訊。LintResult 類型的 suppressedMessages 屬性包含它。它具有以下屬性：

• ruleId (string | null)
  與 LintMessage 類型中的 ruleId 相同。
• severity (1 | 2)
  與 LintMessage 類型中的 severity 相同。
• fatal (boolean | undefined)
  與 LintMessage 類型中的 fatal 相同。
• message (string)
  與 LintMessage 類型中的 message 相同。
• messageId (string | undefined)
  與 LintMessage 類型中的 messageId 相同。
• line (number | undefined)
  與 LintMessage 類型中的 line 相同。
• column (number | undefined)
  與 LintMessage 類型中的 column 相同。
• endLine (number | undefined)
  與 LintMessage 類型中的 endLine 相同。
• endColumn (number | undefined)
  與 LintMessage 類型中的 endColumn 相同。
• fix (EditInfo | undefined)
  與 LintMessage 類型中的 fix 相同。
• suggestions ({ desc: string; fix: EditInfo; messageId?: string; data?: object }[] | undefined)
  與 LintMessage 類型中的 suggestions 相同。
• suppressions ({ kind: string; justification: string}[])
  抑制清單。每個抑制都是一種種類和一個理由的配對。

◆ EditInfo 型別

EditInfo 值是用於編輯文字的資訊。LintMessage 類型的 fix 和 suggestions 屬性包含它。它具有以下屬性：

• range ([number, number])
  要移除的原始碼文字中以 0 為基礎的索引配對。
• text (string)
  要加入的文字。

此編輯資訊表示將 range 屬性的範圍替換為 text 屬性值。就像 sourceCodeText.slice(0, edit.range[0]) + edit.text + sourceCodeText.slice(edit.range[1]) 一樣。因此，如果 range[0] 和 range[1] 屬性值相同，則為新增，如果 text 屬性值為空字串，則為移除。

◆ LoadedFormatter 型別

LoadedFormatter 值是將 LintResult 物件轉換為文字的物件。eslint.loadFormatter() 方法會回傳它。它具有以下方法：

• format ((results: LintResult[], resultsMeta?: ResultsMeta) => string | Promise<string>)
  將 LintResult 物件轉換為文字的方法。resultsMeta 是一個選用參數，主要用於 ESLint CLI，並且只能包含一個 maxWarningsExceeded 屬性，當此方法呼叫底層的格式化工具函式時，該屬性會透過 context 物件傳遞。請注意，ESLint 會自動產生 context 物件的 cwd 和 rulesMeta 屬性，因此在呼叫此方法時，您通常不需要傳入第二個引數。

---

loadESLint()

loadESLint() 函式用於希望同時支援目前設定系統（扁平設定）和舊設定系統（eslintrc）的整合。此函式會根據提供的引數回傳正確的 ESLint 類別實作。

const { loadESLint } = require("eslint");

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();

// loads the flat config version specifically
const FlatESLint = await loadESLint({ useFlatConfig: true });

// loads the legacy version specifically
const LegacyESLint = await loadESLint({ useFlatConfig: false });
1
2
3
4
5
6
7
8
9
10

然後，您可以使用回傳的建構函式來實例化新的 ESLint 實例，如下所示：

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();
const eslint = new DefaultESLint();
1
2
3

如果您不確定回傳的建構函式使用哪個設定系統，請檢查 configType 屬性，該屬性為 "flat" 或 "eslintrc"。

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();

if (DefaultESLint.configType === "flat") {
    // do something specific to flat config
}
1
2
3
4
5
6

如果您不需要同時支援舊的和新的設定系統，那麼建議直接使用 ESLint 建構函式。

---

SourceCode

SourceCode 類型表示 ESLint 執行的已剖析原始碼。它在 ESLint 內部使用，並且也可以使用，以便可以使用已剖析的程式碼。您可以透過傳入表示程式碼的文字字串和 ESTree 格式的抽象語法樹 (AST)（包括位置資訊、範圍資訊、註解和 token）來建立新的 SourceCode 實例。

const SourceCode = require("eslint").SourceCode;

const code = new SourceCode("var foo = bar;", ast);
1
2
3

如果 AST 遺失任何必要的資訊，SourceCode 建構函式會擲回錯誤。

SourceCode 建構函式會移除 Unicode BOM。請注意，AST 也應該從已移除的文字剖析。

const SourceCode = require("eslint").SourceCode;

const code = new SourceCode("\uFEFFvar foo = bar;", ast);

assert(code.hasBOM === true);
assert(code.text === "var foo = bar;");
1
2
3
4
5
6

SourceCode#splitLines()

這是 SourceCode 上的靜態函式，用於將原始碼文字分割成多行陣列。

const SourceCode = require("eslint").SourceCode;

const code = "var a = 1;\nvar b = 2;"

// split code into an array
const codeLines = SourceCode.splitLines(code);

/*
    Value of codeLines will be
    [
        "var a = 1;",
        "var b = 2;"
    ]
 */
1
2
3
4
5
6
7
8
9
10
11
12
13
14

---

Linter

Linter 物件會實際評估 JavaScript 程式碼。它不會執行任何檔案系統操作，它只會解析並回報程式碼。特別是，Linter 物件不會處理設定檔。除非您是在瀏覽器中工作，否則您可能想要改用 ESLint 類別。

Linter 是一個建構函式，您可以傳入您想要使用的選項來建立新的實例。可用的選項如下：

• cwd - 應該視為目前工作目錄的路徑。規則可以透過 context.cwd 或呼叫 context.getCwd() 來存取它（請參閱Context 物件）。如果 cwd 是 undefined，如果定義了全域 process 物件（例如，在 Node.js 執行環境中），它會正規化為 process.cwd()，否則會是 undefined。

例如：

const Linter = require("eslint").Linter;
const linter1 = new Linter({ cwd: 'path/to/project' });
const linter2 = new Linter();
1
2
3

在這個範例中，在 linter1 上執行的規則會從 context.cwd 或呼叫 context.getCwd() 時取得 path/to/project。在 linter2 上執行的規則，如果定義了全域 process 物件，則會取得 process.cwd()，否則會取得 undefined（例如，在瀏覽器 https://eslint.dev.org.tw/demo 上）。

Linter#verify

Linter 上最重要的的方法是 verify()，它會啟動給定文字的 linting。此方法接受三個參數：

• code - 要進行 lint 的原始碼（字串或 SourceCode 的實例）。
• config - 一個 設定物件 或設定物件的陣列。
  • 注意：如果您想要 lint 文字並讓設定從檔案系統讀取，請改用 ESLint#lintFiles() 或 ESLint#lintText()。
• options -（選用）此執行中的其他選項。
  • filename -（選用）與原始碼關聯的檔案名稱。
  • preprocess -（選用）外掛程式中的處理器 文件中描述為 preprocess 方法的函式。
  • postprocess -（選用）外掛程式中的處理器 文件中描述為 postprocess 方法的函式。
  • filterCodeBlock -（選用）一個函式，決定 linter 應該採用哪些程式碼區塊。該函式接收兩個參數。第一個參數是程式碼區塊的虛擬檔案名稱。第二個參數是程式碼區塊的文字。如果函式傳回 true，則 linter 會採用該程式碼區塊。如果省略了該函式，則 linter 只會採用 *.js 程式碼區塊。如果您提供了 filterCodeBlock 函式，它會覆寫此預設行為，因此 linter 不會自動採用 *.js 程式碼區塊。
  • disableFixes -（選用）當設定為 true 時，linter 不會建立 lint 結果的 fix 或 suggestions 屬性。
  • allowInlineConfig -（選用）設定為 false 以停用內嵌註解變更 ESLint 規則。
  • reportUnusedDisableDirectives -（選用）當設定為 true 時，當在停用區域中不會回報任何問題時，會針對未使用的 eslint-disable 和 eslint-enable 指示詞新增回報的錯誤。
  • ruleFilter -（選用）一個函式謂詞，決定應該執行哪些規則。它會接收一個包含 ruleId 和 severity 的物件，如果應該執行規則，則會傳回 true。

如果第三個參數是字串，則會將其解讀為 filename。

您可以像這樣呼叫 verify()：

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify("var foo;", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

// or using SourceCode

const Linter = require("eslint").Linter,
    linter = new Linter(),
    SourceCode = require("eslint").SourceCode;

const code = new SourceCode("var foo = bar;", ast);

const messages = linter.verify(code, {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

verify() 方法會傳回一個物件陣列，其中包含有關 linting 警告和錯誤的資訊。以下是一個範例：

[
    {
        fatal: false,
        ruleId: "semi",
        severity: 2,
        line: 1,
        column: 23,
        message: "Expected a semicolon.",
        fix: {
            range: [1, 15],
            text: ";"
        }
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14

每個 linting 訊息可用的資訊如下：

• column - 發生錯誤的欄位。
• fatal - 通常會省略，但如果有解析錯誤（與規則無關），則會設定為 true。
• line - 發生錯誤的行。
• message - 應該輸出的訊息。
• messageId - 用於產生訊息的訊息 ID（如果規則未使用訊息 ID，則會省略此屬性）。
• nodeType -（已棄用：此屬性將在未來版本的 ESLint 中移除。）使用問題回報的節點或權杖類型。
• ruleId - 觸發訊息的規則 ID（如果 fatal 為 true，則為 null）。
• severity - 1 或 2，取決於您的設定。
• endColumn - 發生錯誤的範圍的結束欄（如果不是範圍，則會省略此屬性）。
• endLine - 發生錯誤的範圍的結束行（如果不是範圍，則會省略此屬性）。
• fix - 一個描述問題修正的物件（如果沒有可用的修正，則會省略此屬性）。
• suggestions - 一個物件陣列，描述編輯器可程式化啟用的可能的 lint 修正（請參閱 使用規則文件 中的詳細資訊）。

您可以透過 getSuppressedMessages() 方法取得先前執行中被抑制的訊息。如果沒有先前的執行，getSuppressedMessage() 將會傳回空清單。

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify("var foo = bar; // eslint-disable-line -- Need to suppress", {
    rules: {
        semi: ["error", "never"]
    }
}, { filename: "foo.js" });
const suppressedMessages = linter.getSuppressedMessages();

console.log(suppressedMessages[0].suppressions); // [{ "kind": "directive", "justification": "Need to suppress" }]
1
2
3
4
5
6
7
8
9
10
11

您也可以使用 getSourceCode() 方法取得 linter 內部使用的 SourceCode 物件的實例：

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify("var foo = bar;", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

const code = linter.getSourceCode();

console.log(code.text);     // "var foo = bar;"
1
2
3
4
5
6
7
8
9
10
11
12

這樣，您可以檢索最後一次執行 linter.verify() 時使用的文字和 AST。

Linter#verifyAndFix()

此方法類似於 verify，只不過它還會執行自動修正邏輯，類似於命令列上的 --fix 旗標。結果物件將包含自動修正的程式碼，以及程式碼中未自動修正的任何剩餘 linting 訊息。

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verifyAndFix("var foo", {
    rules: {
        semi: 2
    }
});
1
2
3
4
5
6
7
8

此方法的輸出物件：

{
    fixed: true,
    output: "var foo;",
    messages: []
}
1
2
3
4
5

可用的資訊如下：

• fixed - 如果程式碼已修正，則為 True。
• output - 已修正的程式碼文字（如果沒有套用修正，則可能與輸入相同）。
• messages - 給定程式碼的所有訊息集合（它具有與上述 verify 區塊下說明相同的資訊）。

Linter#version/Linter.version

Linter 的每個實例都有一個 version 屬性，其中包含 Linter 實例來自的 ESLint 的語意版本號碼。

const Linter = require("eslint").Linter;
const linter = new Linter();

linter.version; // => '9.0.0'
1
2
3
4

還有一個 Linter.version 屬性，您可以在不實例化 Linter 的情況下讀取該屬性：

const Linter = require("eslint").Linter;

Linter.version; // => '9.0.0'
1
2
3

Linter#getTimes()

此方法用於取得花費在檔案上的時間（解析、修正、linting）。請參閱 統計資料 物件的 times 屬性。

Linter#getFixPassCount()

此方法用於取得所做的自動修正次數。請參閱 統計資料 物件的 fixPasses 屬性。

Linter#hasFlag()

此方法用於判斷是否已設定給定的功能標誌，如下例所示：

const Linter = require("eslint").Linter;
const linter = new Linter({ flags: ["x_feature"] });

console.log(linter.hasFlag("x_feature")); // true
1
2
3
4

---

RuleTester

eslint.RuleTester 是一個用於撰寫 ESLint 規則測試的公用程式。它在內部用於 ESLint 隨附的捆綁規則，也可以由外掛程式使用。

用法範例：

"use strict";

const rule = require("../../../lib/rules/my-rule"),
    RuleTester = require("eslint").RuleTester;

const ruleTester = new RuleTester();

ruleTester.run("my-rule", rule, {
    valid: [
        {
            code: "var foo = true",
            options: [{ allowFoo: true }]
        }
    ],

    invalid: [
        {
            code: "var invalidVariable = true",
            errors: [{ message: "Unexpected invalid variable." }]
        },
        {
            code: "var invalidVariable = true",
            errors: [{ message: /^Unexpected.+variable/ }]
        }
    ]
});
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
26

RuleTester 建構函式接受一個選用的物件引數，可用於指定測試案例的預設值。例如，如果您的所有測試案例都使用 ES2015，您可以將其設定為預設值：

const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 2015 } });
1

RuleTester#run() 方法用於執行測試。應該傳遞以下引數：

• 規則的名稱（字串）。
• 規則物件本身（請參閱「使用規則」）。
• 一個包含 valid 和 invalid 屬性的物件，每個屬性都是一個包含測試案例的陣列。

測試案例是一個具有以下屬性的物件：

• name（字串，選用）：用於測試案例的名稱，使其更容易找到。
• code（字串，必要）：應該在其上執行規則的原始碼。
• options（陣列，選用）：傳遞給規則的選項。規則嚴重性不應包含在此清單中。
• before（函式，選用）：在測試案例之前執行的函式。
• after（函式，選用）：在測試案例之後執行的函式，無論其結果如何。
• filename（字串，選用）：給定案例的檔案名稱（對於對檔案名稱進行斷言的規則很有用）。
• only（布林值，選用）：僅執行此案例以在支援的測試框架中進行偵錯。

除了以上屬性之外，無效的測試案例也可以具有以下屬性：

• errors（數字或陣列，必要）：斷言規則在對此程式碼執行時預期會產生的一些錯誤屬性。如果這是數字，則會斷言產生的錯誤數量。否則，這應該是一個物件清單，每個物件都包含有關單一回報錯誤的資訊。以下屬性可用於錯誤（除非另有說明，否則所有屬性都是選用的）：

  • message（字串/正規表示式）：錯誤的訊息。必須提供此項或 messageId。
  • messageId（字串）：錯誤的 ID。必須提供此項或 message。有關詳細資訊，請參閱使用 messageId 測試錯誤。
  • data（物件）：可以用於與 messageId 結合使用的佔位符資料。
  • type（字串）：（已棄用：此屬性將在未來版本的 ESLint 中移除。）回報的 AST 節點類型。
  • line（數字）：回報位置的基於 1 的行號。
  • column（數字）：回報位置的基於 1 的欄號。
  • endLine（數字）：回報位置結尾的基於 1 的行號。
  • endColumn（數字）：回報位置結尾的基於 1 的欄號。
  • suggestions（陣列）：一個包含要檢查的建議詳細資訊的物件陣列。如果規則產生建議，則為必要項目。有關詳細資訊，請參閱測試建議。

  如果提供字串作為錯誤而不是物件，則該字串會用於斷言錯誤的 message。

• output（字串，如果規則修正程式碼則為必要項目）：斷言當使用此規則進行單一自動修正傳遞時（例如，使用 --fix 命令列旗標）將產生的輸出。如果此項為 null 或省略，則斷言回報的問題都沒有建議自動修正。

測試案例的任何其他屬性都將直接作為設定選項傳遞給 linter。例如，測試案例可以具有 languageOptions 屬性來設定剖析器行為：

{
    code: "let foo;",
    languageOptions: { ecmaVersion: 2015 }
}
1
2
3
4

如果有效的測試案例僅使用 code 屬性，則它可以選擇以包含程式碼的字串形式提供，而不是使用具有 code 鍵的物件。

使用 messageId 測試錯誤

如果受測規則使用 messageId，您可以在測試案例中使用 messageId 屬性來斷言回報錯誤的 messageId，而不是其 message。

{
    code: "let foo;",
    errors: [{ messageId: "unexpected" }]
}
1
2
3
4

對於帶有佔位符的訊息，測試案例也可以使用 data 屬性來額外斷言回報錯誤的 message。

{
    code: "let foo;",
    errors: [{ messageId: "unexpected", data: { name: "foo" } }]
}
1
2
3
4

請注意，測試案例中的 data 並不會斷言傳遞給 context.report 的 data。相反地，它用於形成預期的訊息文字，然後與收到的 message 進行比較。

測試修正

套用修復的結果可以透過使用無效測試案例的 output 屬性來測試。 output 屬性應該只在您期望對指定的 code 套用修復時使用；如果預期程式碼不會有任何變更，您可以安全地省略 output。以下是一個範例

ruleTester.run("my-rule-for-no-foo", rule, {
    valid: [],
    invalid: [{
        code: "var foo;",
        output: "var bar;",
        errors: [{
            messageId: "shouldBeBar",
            line: 1,
            column: 5
        }]
    }]
})
1
2
3
4
5
6
7
8
9
10
11
12

在這種無效的測試案例結束時，RuleTester 預期會套用一個修復，導致程式碼從 var foo; 變更為 var bar;。如果套用修復後的輸出不符，則測試會失敗。

測試建議

建議可以使用錯誤物件上的 suggestions 鍵來測試。如果這是一個數字，它會斷言為該錯誤提供的建議數量。否則，這應該是一個物件陣列，每個物件都包含有關單一提供的建議的資訊。可以使用以下屬性

• desc (字串)：建議的 desc 值。必須提供此項或 messageId
• messageId (字串)：使用 messageId 的建議的 messageId 值。必須提供此項或 desc
• data (物件)：可以與 messageId 結合使用的佔位符資料。
• output (字串，必要)：一個程式碼字串，代表將建議修復套用到輸入程式碼的結果

範例

ruleTester.run("my-rule-for-no-foo", rule, {
    valid: [],
    invalid: [{
        code: "var foo;",
        errors: [{
            suggestions: [{
                desc: "Rename identifier 'foo' to 'bar'",
                output: "var bar;"
            }]
        }]
    }]
})
1
2
3
4
5
6
7
8
9
10
11
12

建議測試物件中的 messageId 和 data 屬性與錯誤測試物件中的運作方式相同。有關詳細資訊，請參閱使用 messageId 測試錯誤。

ruleTester.run("my-rule-for-no-foo", rule, {
    valid: [],
    invalid: [{
        code: "var foo;",
        errors: [{
            suggestions: [{
                messageId: "renameFoo",
                data: { newName: "bar" },
                output: "var bar;"
            }]
        }]
    }]
})
1
2
3
4
5
6
7
8
9
10
11
12
13

自訂 RuleTester

RuleTester 依賴兩個函數來執行測試：describe 和 it。這些函數可以來自不同的地方

1. 如果 RuleTester.describe 和 RuleTester.it 已設定為函數值，RuleTester 將使用 RuleTester.describe 和 RuleTester.it 來執行測試。您可以使用此功能來自訂 RuleTester 的行為，使其符合您正在使用的測試框架。

   如果 RuleTester.itOnly 已設定為函數值，RuleTester 將呼叫 RuleTester.itOnly 而不是 RuleTester.it 來執行具有 only: true 的案例。如果 RuleTester.itOnly 未設定，但 RuleTester.it 具有 only 函數屬性，RuleTester 將會退回到 RuleTester.it.only。

2. 否則，如果 describe 和 it 作為全域變數存在，RuleTester 將使用 globalThis.describe 和 globalThis.it 來執行測試，並使用 globalThis.it.only 來執行具有 only: true 的案例。這允許 RuleTester 在使用像 Mocha 這樣的框架時，無需任何額外的設定即可運作。

3. 否則，RuleTester#run 只會依序執行所有測試，並且如果其中一個測試失敗，則會擲回錯誤。這表示您可以使用 Node.js 簡單地執行呼叫 RuleTester.run 的測試檔案，而無需測試框架。

RuleTester#run 使用兩個參數呼叫 describe 函數：一個描述規則的字串，以及一個回呼函數。回呼函數使用一個描述測試案例的字串和一個測試函數呼叫 it 函數。如果測試通過，測試函數將成功返回，如果測試失敗，則會擲回錯誤。 only 的簽名與 it 相同。即使某些案例具有 only: true，RuleTester 也會為每個案例呼叫 it 或 only，而測試框架負責實作測試案例的排他性。（請注意，這是使用像 Mocha 這樣的框架時，測試套件的標準行為；只有當您打算自訂 RuleTester.describe、RuleTester.it 或 RuleTester.itOnly 時，此資訊才相關。）

自訂 RuleTester 的範例

"use strict";

const RuleTester = require("eslint").RuleTester,
    test = require("my-test-runner"),
    myRule = require("../../../lib/rules/my-rule");

RuleTester.describe = function(text, method) {
    RuleTester.it.title = text;
    return method.call(this);
};

RuleTester.it = function(text, method) {
    test(RuleTester.it.title + ": " + text, method);
};

// then use RuleTester as documented

const ruleTester = new RuleTester();

ruleTester.run("my-rule", myRule, {
    valid: [
        // valid test cases
    ],
    invalid: [
        // invalid test cases
    ]
})
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
26
27