eslint-docs

ESLint 10

此技能涵蓋 ESLint 10.14.0，內容基於 https://eslint.org/docs/latest/。它專注於與習慣不同的部分：flat config 的陷阱、令人意外的預設值、已移除的 API，以及文件推薦的模式。每個參考檔案中的論點皆附有來源頁面。

如何導覽

1. 閱讀下列快速規則。它們能抓住最常見的錯誤。
2. 根據結尾的表格，開啟與任務相符的其中一個參考檔案。
3. 當程式碼使用 .eslintrc、env、context.getScope() 或 FlatESLint 時，請先閱讀 references/migration.md。

快速開始

npm init @eslint/config@latest

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

export default defineConfig([
  globalIgnores(["dist/"]),
  {
    files: ["**/*.js", "**/*.mjs", "**/*.cjs"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: { globals: { ...globals.browser } },
    rules: { "no-unused-vars": "warn" },
  },
]);

https://eslint.org/docs/latest/use/getting-started , https://eslint.org/docs/latest/use/configure/configuration-files

• Node.js ^20.19.0、^22.13.0 或 >=24。TypeScript 類型需要 TypeScript 5.3 以上版本。 https://eslint.org/docs/latest/use/getting-started
• 將 eslint 和 @eslint/js 作為開發依賴進行本地安裝。不建議全域安裝，且外掛仍必須是本地安裝。globals 是一個單獨的套件。 https://eslint.org/docs/latest/use/getting-started , https://eslint.org/docs/latest/use/configure/migration-guide
• eslint.config.ts 需要在 Node 上安裝開發依賴 jiti >= 2.2.0。 https://eslint.org/docs/latest/use/configure/configuration-files

快速規則

設定檔

• 在擴充設定或啟用規則之前，ESLint 不會對任何有用的內容進行 lint。 https://eslint.org/docs/latest/use/getting-started
• 設定查找從每個被 lint 檔案的目錄開始，並向上遍歷。--config 會強制使用單一檔案。 https://eslint.org/docs/latest/use/configure/configuration-files , https://eslint.org/docs/latest/use/migrate-to-10.0.0
• 沒有 files 屬性的物件會套用至另一個物件匹配到的每一個檔案。一旦你對 .ts、.md 或 .json 進行 lint，請使用 files 限定 JS 規則範圍，並始終將 files 放在 extends 旁邊。 https://eslint.org/docs/latest/use/configure/configuration-files
• 物件中單獨存在的 ignores（全域忽略）可以匹配目錄。與其他鍵並存時，它僅匹配檔案：使用 "dir/**"，而非 "dir/"。建議優先使用 globalIgnores()。 https://eslint.org/docs/latest/use/configure/configuration-files
• 除非被忽略，否則點檔案也會被 lint。預設情況下，僅有 **/node_modules/ 和 .git/ 被忽略。 https://eslint.org/docs/latest/use/configure/ignore , https://eslint.org/docs/latest/use/configure/configuration-files
• 使用來自 eslint/config 的 includeIgnoreFile(path, { gitignoreResolution: true }) 匯入 .gitignore。 https://eslint.org/docs/latest/use/configure/ignore
• 沒有環境變數：使用 globals 套件在 languageOptions.globals 中宣告全域變數。 https://eslint.org/docs/latest/use/configure/language-options
• 外掛、解析器和處理器是匯入的物件。處理器永遠不會自動套用。 https://eslint.org/docs/latest/use/configure/migration-guide
• 使用 npx eslint --inspect-config 或 --print-config file.js 檢查哪些檔案匹配。 https://eslint.org/docs/latest/use/configure/debug

規則與註解

• 僅重新指定嚴重程度的行為會保留先前的選項，這同時適用於設定檔和 /* eslint */ 註解。 https://eslint.org/docs/latest/use/configure/rules , https://eslint.org/docs/latest/use/migrate-to-9.0.0
• 行內註解無法載入外掛。單獨的 /* eslint-enable */ 會重新啟用所有規則。 https://eslint.org/docs/latest/use/configure/rules
• 在 -- 之後加上原因：// eslint-disable-next-line no-console -- reason。 https://eslint.org/docs/latest/use/configure/rules
• 在 ESLint 10 中，/* eslint-env */ 會導致錯誤。請使用 /* global name */ 或設定全域變數。 https://eslint.org/docs/latest/use/migrate-to-10.0.0
• no-unused-vars 預設會報告未使用的 catch (e)：請改寫為 catch {。 https://eslint.org/docs/latest/rules/no-unused-vars
• 不要啟用 no-return-await。使用格式化工具或 ESLint Stylistic，而非核心版面規則。 https://eslint.org/docs/latest/rules/no-return-await , https://eslint.org/docs/latest/use/core-concepts/glossary

CLI 與 CI

• 退出碼 1 代表有錯誤（或太多警告），退出碼 2 代表設定或內部錯誤。 https://eslint.org/docs/latest/use/command-line-interface
• --quiet 不會執行 "warn" 規則，除非同時設定了 --max-warnings：在這種情況下，規則會執行但不會被回報。 https://eslint.org/docs/latest/use/command-line-interface
• 請使用引號包裹 glob 模式。使用標準輸入時 --fix 會拋出錯誤：請改用 --fix-dry-run --format json。 https://eslint.org/docs/latest/use/command-line-interface
• --cache 會忽略跨檔案依賴關係：基於類型的規則和匯入規則可能會過時。 https://eslint.org/docs/latest/use/command-line-interface
• 使用 eslint --fix --suppress-all 對舊程式碼採用嚴格的規則，並提交 eslint-suppressions.json。 https://eslint.org/docs/latest/use/suppressions

自訂規則與整合

• 一個規則是 { meta, create }。需要修復或建議時必須提供 meta.fixable 和 meta.hasSuggestions，若規則接受選項則必須提供 meta.schema。 https://eslint.org/docs/latest/extend/custom-rules
• 使用 context.sourceCode、context.filename 和 sourceCode.getScope(node)。context.getX() 方法已不復存在。 https://eslint.org/docs/latest/use/migrate-to-10.0.0 , https://eslint.org/docs/latest/use/migrate-to-9.0.0
• new ESLint({ fix: true }) 在呼叫 ESLint.outputFixes(results) 之前不會寫入任何內容。 https://eslint.org/docs/latest/integrate/nodejs-api
• 為外掛提供 meta.name、meta.version 和 meta.namespace，以便於除錯並提高快取效率。命名空間讓 defineConfig() 能夠以其他名稱找到此外掛。 https://eslint.org/docs/latest/extend/plugins

舊有模式

舊有	目前
.eslintrc.*、package.json 中的 eslintConfig	使用 defineConfig() 的 eslint.config.js
"extends": "eslint:recommended"	搭配 plugins: { js } 使用 extends: ["js/recommended"]
env、/* eslint-env */	languageOptions.globals、/* global */
.eslintignore、--ignore-path	globalIgnores()、includeIgnoreFile()
overrides	更多帶有 files 屬性的設定物件
--rulesdir、linter.defineRule()	行內外掛 plugins: { local: { rules } }
--no-eslintrc	--no-config-lookup
context.getScope()、context.getSourceCode()	sourceCode.getScope(node)、context.sourceCode
函數風格的規則	{ meta, create }
FlatESLint、LegacyESLint、FlatRuleTester	ESLint、RuleTester
require-jsdoc、valid-jsdoc	eslint-plugin-jsdoc

詳細資訊和完整清單：references/migration.md。

參考檔案

檔案	閱讀時機
references/configuration.md	設定檔名稱與查找、TypeScript 設定、設定物件鍵值、files 匹配、extends、語言選項、全域變數、解析器、處理器、語言、除錯
references/ignoring-files.md	全域與非全域 ignores、預設忽略、點檔案、取消忽略方法、.gitignore 匯入
references/rules-and-inline-config.md	嚴重程度、選項合併、行內設定註解、停用指令、linterOptions、修復與建議、循環修復
references/cli.md	Glob 模式、--fix、退出碼、--quiet、格式化工具、快取、大量抑制、功能標誌、並發、MCP 伺服器
references/migration.md	ESLint 9 和 10 的重大變更、codemod、eslintrc 到 flat config、已更改的規則選項、受損的外掛
references/custom-rules.md	規則 meta、本地規則、context.report、修復、建議、meta.schema、meta.defaultOptions、棄用、已移除的 context 方法
references/ast-scope-code-paths.md	Selectors、SourceCode 方法、Scope、Scope 管理器物件、程式碼路徑事件、效能分析
references/testing-rules.md	RuleTester 預設值、有效與無效案例、修復與建議斷言、嚴格檢查、框架鉤子
references/plugins-and-shareable-configs.md	外掛物件與 meta、外掛設定、發佈、可共享設定、自訂解析器、處理器、語言、格式化工具
references/nodejs-api.md	ESLint 選項與方法、lintText、outputFixes、loadFormatter、LintResult、Linter、SourceCode
references/core-rules-problems.md	TypeScript 涵蓋的規則、未使用與未宣告的變數、變數遮蔽、條件判斷、非同步錯誤、正規表達式陷阱
references/core-rules-restrictions.md	no-restricted-imports、-globals、-properties、-exports、no-restricted-syntax 配方、其他禁令、大小與複雜度限制
references/core-rules-style.md	建議規則預設值、版面規則預設值、已移除的規則、已棄用的選項

爬取的頁面：SOURCES.md。