【翻译】ESLint v10.0.0 正式发布

原文链接：eslint.org/blog/2026/0…

作者：@nzakas

我们刚刚发布了 ESLint v10.0.0 版本，这是 ESLint 的一次重大版本升级。该版本新增了若干功能，修复了上一版本中发现的多个漏洞，同时也包含一些破坏性变更，请务必仔细阅读以下内容。

核心亮点

ESLint v10.0.0 作为重大版本更新，包含多项新功能与破坏性变更。以下是本次更新中最值得关注的内容。

安装说明

由于这是一次重大版本更新，npm 不会自动为你升级至该版本。如需确保使用此版本，请执行以下命令：

npm i eslint@10.0.0 --save-dev

废弃对旧版 Node.js 的支持

截至本文发布时，Node.js v24.x 已成为长期支持（LTS）版本，因此我们将停止支持 Node.js v20.19.0 之前的所有版本，以及 v21.x 和 v23.x 系列版本。

迁移指南

本次更新包含大量变更，我们专门编写了一份迁移指南，其中详细说明所有破坏性变更，以及你需要采取的应对步骤。我们预计大多数用户无需修改构建配置即可完成升级，但如果遇到问题，这份迁移指南将是重要的参考资料。

全新的配置文件查找算法

ESLint v10.0.0 会从每个被检查文件的所在目录开始查找 eslint.config.* 配置文件，而非 ESLint v9.x 中从当前工作目录开始查找的方式。新的查找逻辑允许在单次检查中使用多个配置文件，这在单体仓库（monorepo） 架构中尤为实用。

在 ESLint v9.x 中，可通过启用 v10_config_lookup_from_file 功能标志来开启该配置查找逻辑；而在 ESLint v10.0.0 中，此逻辑已成为默认行为，且 v10_config_lookup_from_file 标志已被移除。

移除 eslintrc 相关功能

正如扁平配置（Flat config）推出计划中所公告的，ESLint v10.0.0 已彻底移除 eslintrc 配置系统。具体变更如下：

• 环境变量 ESLINT_USE_FLAT_CONFIG 不再生效；
• 命令行（CLI）不再支持 eslintrc 专属参数（--no-eslintrc、--env、--resolve-plugins-relative-to、--rulesdir、--ignore-path）；
• .eslintrc.* 和 .eslintignore 文件将不再被识别；
• /* eslint-env */ 注释会被标记为错误；
• loadESLint() 函数现在始终返回 ESLint 类；
• Linter 构造函数的 configType 参数仅支持传入 "flat"，若传入 "eslintrc" 会抛出错误；
• 以下 Linter 类中 eslintrc 专属方法被移除：
  • defineParser()
  • defineRule()
  • defineRules()
  • getRules()
• 对 /use-at-your-own-risk 入口的变更：
  • 移除 LegacyESLint
  • 移除 FileEnumerator
  • shouldUseFlatConfig() 函数将始终返回 true

新增 JSX 引用追踪能力

ESLint v10.0.0 现在会追踪 JSX 引用，从而实现对 JSX 元素的精准作用域分析。

此前，JSX 标识符不会被作为引用追踪，这可能导致依赖作用域信息的规则返回错误结果。例如：

import { Card } from "./card.jsx";

export function createCard(name) {
  return <Card name={name} />;
}

v10.0.0 版本之前的问题：

• 误报（False positives） ：<Card> 组件可能被标记为 “已定义但从未使用”（触发 no-unused-vars 规则）；
• 漏报（False negatives） ：移除 <Card> 的导入语句后，可能不会触发 “未定义变量” 错误（no-undef 规则）。

从 v10.0.0 版本开始，<Card> 会被视为作用域内变量的普通引用。这一变更消除了令人困惑的误报 / 漏报问题，让 JSX 的处理逻辑符合开发者的预期，同时提升了使用 JSX 项目的代码检查体验。

Espree 和 ESLint Scope 新增内置类型定义

从 Espree v11.1.0 和 ESLint Scope v9.1.0 版本起，这两个包已内置类型定义文件。

此前，类型定义由 Definitely Typed 社区维护的 @types/espree 和 @types/eslint-scope 包提供。新旧类型定义存在若干差异（主要为 bug 修复），若你的代码依赖这两个包的类型定义，请检查是否需要适配更新。

RuleTester 能力增强

自诞生以来，ESLint 便提供 RuleTester API，帮助插件开发者基于自定义测试用例和配置验证规则逻辑。本次版本对 RuleTester 进行了多项增强，旨在强化测试定义的健壮性，并提升调试体验。

断言选项（Assertion options）

RuleTester#run() 方法新增断言选项 —— 具体包括 requireMessage、requireLocation 和 requireData，允许开发者为规则测试设置更严格的校验要求。这些选项强制要求每个无效测试用例显式校验违规提示信息、位置和数据，若未满足要求则测试直接失败。

• requireMessage
  • 作用：确保每个测试用例都包含提示信息校验；
  • 可接受值：
    • true：必须使用对象数组形式定义 errors（而非数字简写形式）来校验规则报告的问题，且每个对象需像往常一样包含 message 或 messageId 属性，用于校验报告的提示信息；
    • "message"：仅允许通过 message 字段校验；
    • "messageId"：仅允许通过 messageId 字段校验；
  • 目的：防止测试未验证实际提示信息却直接通过。
• requireLocation
  • 作用：确保每个测试用例都包含位置校验；
  • 可接受值：true；
  • 要求：errors 数组中的每个对象必须包含 line（行号）和 column（列号）；若实际报告未包含 endLine 和 endColumn，则这两个字段可选；
  • 目的：保证测试会验证错误的具体位置。
• requireData
  • 作用：确保每个测试用例都包含数据校验；
  • 可接受值：true；
  • 规则：设为 true 时，若 messageId 引用的提示信息包含占位符，RuleTester 会强制要求无效测试用例必须包含 data 对象；这有助于保证测试与依赖占位符替换的规则提示信息保持一致。

示例用法：

ruleTester.run("my-rule", rule, {
  valid: [
    { code: "var foo = true;" }
  ],
  invalid: [
    {
      code: "var invalidVariable = true;",
      errors: [
        { message: "Unexpected invalid variable.", line: 1, column: 5 }
      ]
    }
  ],
  assertionOptions: {
    requireMessage: true,
    requireLocation: true
  }
});

失败测试的位置报告优化

RuleTester 现在会为堆栈跟踪信息补充上下文，帮助开发者更轻松地定位源码中失败的测试用例。例如，测试输出中会新增堆栈跟踪行，明确指出失败用例在 invalid 数组中的索引位置，以及该用例定义所在的文件和行号。

需注意：这些行号信息并非总能显示 —— 具体取决于测试的编写结构。当无法精准确定行号时，仍可通过失败测试的索引值和打印的代码片段定位目标用例。

max-params 规则新增 countThis 选项

max-params 规则新增countThis选项，该选项将取代已废弃的 countVoidThis。当设置 countThis: "never" 时，规则在统计 TypeScript 函数的参数数量时，会忽略函数参数列表中的所有 this 注解。例如：

function doSomething(this: SomeType, first: string, second: number) {
 // ...
}

（注：承接上文 max-params 规则示例）该函数会被判定为仅接收 2 个参数的函数。

格式化器上下文新增 color 属性

当在命令行指定 --color 或 --no-color 选项时，ESLint 会在传递给格式化器的上下文对象（即 format() 方法的第二个参数）中新增 color 属性：

• 传入 --color 时，color 为 true；
• 传入 --no-color 时，color 为 false。

自定义格式化器可基于该值判断是否应用彩色样式 —— 此逻辑默认认为终端对颜色的支持状态与命令行选项一致。

eslint:recommended 配置更新

eslint:recommended 推荐配置已更新，新增了我们认为重要的新规则。

移除已废弃的规则上下文成员

以下规则上下文（rule context）成员已不再可用：

• context.getCwd() → 改用 context.cwd
• context.getFilename() → 改用 context.filename
• context.getPhysicalFilename() → 改用 context.physicalFilename
• context.getSourceCode() → 改用 context.sourceCode
• context.parserOptions → 改用 context.languageOptions 或 context.languageOptions.parserOptions
• context.parserPath → 无替代方案

移除已废弃的 SourceCode 方法

以下 SourceCode 类方法已不再可用：

• getTokenOrCommentBefore() → 改用 getTokenBefore() 并传入 { includeComments: true } 选项
• getTokenOrCommentAfter() → 改用 getTokenAfter() 并传入 { includeComments: true } 选项
• isSpaceBetweenTokens() → 改用 isSpaceBetween()
• getJSDocComment() → 无替代方案

Program AST 节点的 range 覆盖完整源码文本

从 ESLint v10.0.0 开始，Program 类型 AST 节点的 range 属性会覆盖整个源码文本。此前，该范围未包含开头和结尾的注释 / 空白字符。

停止支持 Jiti < v2.2.0 版本

加载 TypeScript 配置文件时，ESLint v10.0.0 不再支持 2.2.0 之前的 Jiti 版本 —— 这是因为旧版本存在已知问题，可能导致加载特定插件时出现兼容性故障。

重大变更（Breaking Changes）

• f9e54f4 新功能（重大）：优化 RuleTester 失败用例位置定位逻辑 (#20420) (ST-DDT)
• a176319 新功能（重大）：用 styleText 替代 chalk，并为 ResultsMeta 添加 color 属性 (#20227) (루밀LuMir)
• c7046e6 新功能（重大）：启用 JSX 引用追踪功能 (#20152) (Pixel998)
• fa31a60 新功能（重大）：为配置项添加name属性 (#20015) (Kirk Waiblinger)
• 3383e7e 修复（重大）：移除已废弃的 SourceCode 方法 (#20137) (Pixel998)
• 501abd0 新功能（重大）：将依赖 minimatch 升级至 v10 版本 (#20246) (renovate [bot])
• ca4d3b4 修复（重大）：为有效测试用例强化 RuleTester 断言校验规则 (#20125) (唯然)
• 96512a6 修复（重大）：移除已废弃的规则上下文方法 (#20086) (Nicholas C. Zakas)
• c69fdac 新功能（重大）：移除对 eslintrc 配置系统的支持 (#20037) (Francesco Trotta)
• 208b5cc 新功能（重大）：使用 ScopeManager#addGlobals() 方法 (#20132) (Milos Djermanovic)
• a2ee188 修复（重大）：为 no-invalid-regexp 规则选项添加 uniqueItems: true 配置 (#20155) (Tanuj Kanti)
• a89059d 新功能（重大）：让 Program 节点的 range 覆盖完整源码文本 (#20133) (Pixel998)
• 39a6424 修复（重大）：强制所有 RuleFixer 方法校验 'text' 参数为字符串类型 (#20082) (Pixel998)
• f28fbf8 修复（重大）：废弃 radix 规则的 always 和 as-needed 选项 (#20223) (Milos Djermanovic)
• aa3fb2b 修复（重大）：收紧 func-names 规则的 schema 校验 (#20119) (Pixel998)
• f6c0ed0 新功能（重大）：将 /* eslint-env */ 注释标记为错误 (#20128) (Francesco Trotta)
• 4bf739f 修复（重大）：移除已废弃的 LintMessage#nodeType 和 TestCaseError#type 属性 (#20096) (Pixel998)
• 523c076 新功能（重大）：停止支持 jiti < 2.2.0 版本 (#20016) (michael faith)
• 454a292 新功能（重大）：更新 eslint:recommended 推荐配置 (#20210) (Pixel998)
• 4f880ee 新功能（重大）：移除 v10_* 和未启用的 unstable_* 功能标志 (#20225) (sethamus)
• f18115c 新功能（重大）：no-shadow-restricted-names 规则默认检测 globalThis (#20027) (sethamus)
• c6358c3 新功能（重大）：要求 Node.js 版本为 ^20.19.0 || ^22.13.0 || >=24 (#20160) (Milos Djermanovic)

新功能（Features）

• bff9091 新功能：在 array-callback-return 规则中支持 Array.fromAsync 处理 (#20457) (Francesco Trotta)
• 290c594 新功能：为 no-implied-eval 规则添加 self 关键字检测 (#20468) (sethamus)
• 43677de 新功能：修复 no-shadow 规则对函数 / 类表达式名称的处理逻辑 (#20432) (Milos Djermanovic)
• f0cafe5 新功能：RuleTester 新增 requireData 断言选项 (#20409) (fnx)
• f7ab693 新功能：输出 RuleTester 失败测试用例的索引值 (#19976) (ST-DDT)
• 7cbcbf9 新功能：为 max-params 规则添加 countThis 选项 (#20236) (Gerkin)
• f148a5e 新功能：新增错误断言选项 (#20247) (ST-DDT)
• 09e6654 新功能：更新 require-yield 和 no-useless-constructor 规则的错误位置定位 (#20267) (Tanuj Kanti)

漏洞修复（Bug Fixes）

• 436b82f 修复：升级 ESLint 版本依赖 (#20473) (renovate [bot])
• 1d29d22 修复：检测 Array.fromAsync 回调中 this 的默认绑定 (#20456) (Francesco Trotta)
• 727451e 修复：修复 strict 规则中全局模式下报告范围的回归问题 (#20462) (ntnyq)
• e80485f 修复：移除伪造的 FlatESLint 和 LegacyESLint 导出 (#20460) (Francesco Trotta)
• 9eeff3b 修复：升级 esquery 依赖 (#20423) (cryptnix)
• b34b938 修复：使用 Error.prepareStackTrace 优化失败测试位置定位 (#20436) (Francesco Trotta)
• 51aab53 修复：升级 ESLint 版本依赖 (#20443) (renovate [bot])
• 23490b2 修复：处理 RuleTester 位置定位中冒号前的空格问题 (#20433) (Francesco Trotta)
• f244dbf 修复：使用 @eslint/core 中的 MessagePlaceholderData 类型 (#20348) (루밀LuMir)
• d186f8c 修复：升级 ESLint 版本依赖 (#20427) (renovate [bot])
• 2332262 修复：RuleTester 中错误位置信息不应修改错误提示文本 (#20421) (Milos Djermanovic)
• ab99b21 修复：确保 filename 作为第三个参数传入 verifyAndFix() 方法 (#20405) (루밀LuMir)
• 8a60f3b 修复：从 ParserOptions 类型中移除 ecmaVersion 和 sourceType 属性 (#20415) (Pixel998)
• eafd727 修复：移除 TDZ 作用域类型 (#20231) (jaymarvelz)
• 39d1f51 修复：修正 Scope 类型定义 (#20404) (sethamus)
• 2bd0f13 修复：更新 verify 和 verifyAndFix 方法的类型定义 (#20384) (Francesco Trotta)
• ba6ebfa 修复：修正 loadESLint() 和 shouldUseFlatConfig() 的类型定义 (#20393) (루밀LuMir)
• e7673ae 修复：修正 RuleTester 的类型定义 (#20105) (Pixel998)
• 53e9522 修复：严格(strict)校验已移除的格式化器检查逻辑 (#20241) (ntnyq)
• b017f09 修复：修正 no-restricted-import 规则的提示信息 (#20374) (Francesco Trotta)

文档更新（Documentation）

• e978dda 文档：更新 README 文件 (GitHub Actions Bot)
• 4cecf83 文档：更新 README 文件 (GitHub Actions Bot)
• c79f0ab 文档：更新 README 文件 (GitHub Actions Bot)
• 773c052 文档：更新 README 文件 (GitHub Actions Bot)
• f2962e4 文档：补充 meta.docs.frozen 属性的文档说明 (#20475) (Pixel998)
• 8e94f58 文档：修复动名词标题更新导致的锚点链接失效问题 (#20449) (Copilot)
• 1495654 文档：更新 README 文件 (GitHub Actions Bot)
• 0b8ed5c 文档：补充对 :is 选择器别名的支持说明 (#20454) (sethamus)
• 1c4b33f 文档：补充仅支持 ESM 依赖的政策说明 (#20448) (Milos Djermanovic)
• 3e5d38c 文档：修复规则示例中缺失的缩进空格 (#20446) (fnx)
• 63a0c7c 文档：更新 README 文件 (GitHub Actions Bot)
• 65ed0c9 文档：更新 README 文件 (GitHub Actions Bot)
• b0e4717 文档：扩展 [no-await-in-loop] 规则的不适用场景说明 (#20363) (Niklas Hambüchen)
• fca421f 文档：更新 README 文件 (GitHub Actions Bot)
• d925c54 文档：更新 no-lone-blocks 规则中的配置语法 (#20413) (Pixel998)
• 7d5c95f 文档：移除规则示例中冗余的 sourceType: "module" 配置 (#20412) (Pixel998)
• 02e7e71 文档：修正文件扩展名示例中 .mts 通配符模式 (#20403) (Ali Essalihi)
• 264b981 文档：更新 README 文件 (GitHub Actions Bot)
• 5a4324f 文档：明确 no-unused-vars 规则的 local 选项说明 (#20385) (Milos Djermanovic)
• e593aa0 文档：优化文档站点 README 的表述、语法和措辞 (#20370) (Aditya)
• 3f5062e 文档：为规则元数据文档补充 messages 属性说明 (#20361) (Sabya Sachi)
• 9e5a5c2 文档：移除规则文档中的 Examples 标题 (#20364) (Milos Djermanovic)
• 194f488 文档：更新 README 文件 (GitHub Actions Bot)
• 0f5a94a 文档：补充 [class-methods-use-this] 规则的设计目的说明 (#20008) (Kirk Waiblinger)
• df5566f 文档：为所有规则文档添加 Options 章节 (#20296) (sethamus)
• adf7a2b 文档：补充 no-unsafe-finally 规则针对生成器函数的说明 (#20330) (Tom Pereira)
• ef7028c 文档：更新 README 文件 (GitHub Actions Bot)
• fbae5d1 文档：在迁移指南中统一使用 “v10.0.0” 表述 (#20328) (Pixel998)
• 778aa2d 文档：补充忽略默认文件模式的说明 (#20312) (Tanuj Kanti)
• 4b5dbcd 文档：重新排序 v10 迁移指南内容 (#20315) (Milos Djermanovic)
• 5d84a73 文档：更新 README 文件 (GitHub Actions Bot)
• 37c8863 文档：修复 v10 迁移指南中错误的锚点链接 (#20299) (Pixel998)
• 077ff02 文档：新增 migrate-to-10.0.0 迁移文档 (#20143) (唯然)
• 3822e1b 文档：更新 README 文件 (GitHub Actions Bot)

构建相关（Build Related）

• 9f08712 构建：更新 10.0.0-rc.2 版本的变更日志 (Jenkins)
• 1e2c449 构建：更新 10.0.0-rc.1 版本的变更日志 (Jenkins)
• c4c72a8 构建：更新 10.0.0-rc.0 版本的变更日志 (Jenkins)
• 7e4daf9 构建：更新 10.0.0-beta.0 版本的变更日志 (Jenkins)
• a126a2a 构建：为 knip 工具添加 .scss 文件入口配置 (#20389) (Francesco Trotta)
• f5c0193 构建：更新 10.0.0-alpha.1 版本的变更日志 (Jenkins)
• 165326f 构建：更新 10.0.0-alpha.0 版本的变更日志 (Jenkins)

日常维护（Chores）

• 1ece282 维护：在链接检查器中忽略 /docs/v9.x 目录 (#20452) (Milos Djermanovic)
• 034e139 持续集成：为 @html-eslint/eslint-plugin 添加类型集成测试 (#20345) (sethamus)
• f3fbc2f 维护：将 @eslint/js 版本设为 10.0.0 以跳过发布流程 (#20466) (Milos Djermanovic)
• afc0681 维护：移除针对 typescript-eslint 解析器的 scopeManager.addGlobals 补丁 (#20461) (fnx)
• 3e5a173 重构：使用 @eslint/plugin-kit 中的类型定义 (#20435) (Pixel998)
• 11644b1 持续集成：重命名工作流配置 (#20463) (Milos Djermanovic)
• 2d14173 维护：修复文档和注释中的拼写错误 (#20458) (o-m12a)
• 6742f92 测试：为 no-alert 规则的无效用例添加 endLine/endColumn 字段 (#20441) (경하)
• 3e22c82 测试：为 no-template-curly-in-string 测试补充缺失的位置数据 (#20440) (Haeun Kim)
• b4b3127 维护：@eslint/js 发布更新 package.json 配置 (Jenkins)
• f658419 重构：从 JS 语言配置中移除 raw 解析器选项 (#20416) (Pixel998)
• 2c3efb7 维护：从类型测试用例中移除 category 字段 (#20417) (Pixel998)
• 36193fd 维护：从格式化器测试用例中移除 category 字段 (#20418) (Pixel998)
• e8d203b 维护：为 check-rule-examples 工具添加 JSX 语言标签校验 (#20414) (Pixel998)
• bc465a1 维护：固定依赖版本号 (#20397) (renovate [bot])
• 703f0f5 测试：替换 linter 测试中已废弃的规则 (#20406) (루밀LuMir)
• ba71baa 测试：在类型测试中启用严格(strict)模式 (#20398) (루밀LuMir)
• f9c4968 重构：移除 lib/linter/rules.js 文件 (#20399) (Francesco Trotta)
• 6f1c48e 维护：更新 v9.39.2 版本发布相关配置 (Jenkins)
• 54bf0a3 持续集成：新增包管理器测试用例 (github.com/eslint/esli…) (루밀LuMir)
• 3115021 重构：简化 JSDoc 注释检测逻辑 (#20360) (Pixel998)
• 4345b17 维护：将 @eslint-community/regexpp 升级至 4.12.2 (#20366) (루밀LuMir)
• 772c9ee 维护：将 @eslint/eslintrc 依赖升级至 ^3.3.3 (#20359) (renovate [bot])
• 0b14059 维护：@eslint/js 发布更新 package.json 配置 (Jenkins)
• d6e7bf3 持续集成：将 actions/checkout 从 v5 升级至 v6 (#20350) (dependabot [bot])
• 139d456 维护：要求规则文档必须包含指定头部信息 (#20347) (Milos Djermanovic)
• 3b0289c 维护：移除未使用的 .eslintignore 和测试用例 (#20316) (Pixel998)
• a463e7b 维护：将 js-yaml 依赖升级至 v4（安全更新） (#20319) (renovate [bot])
• ebfe905 维护：从 eslint-config-eslint 中移除冗余规则 (#20327) (Milos Djermanovic)
• 88dfdb2 测试：为消息占位符插值添加回归测试 (#20318) (fnx)
• 6ed0f75 维护：跳过 eslint-config-eslint 中的类型检查 (#20323) (Francesco Trotta)
• 1e2cad5 维护：@eslint/js 发布更新 package.json 配置 (Jenkins)
• 9da2679 维护：升级 @eslint/* 系列依赖 (#20321) (Milos Djermanovic)
• 0439794 重构：使用 @eslint/core 中的类型定义 (#20235) (jaymarvelz)
• cb51ec2 测试：清理 SourceCode#traverse 相关测试 (#20289) (Milos Djermanovic)
• 897a347 维护：移除规则测试中对 type 字段的限制 (#20305) (Pixel998)
• d972098 维护：在 renovate 中忽略 prettier 更新以保持与主干同步 (#20304) (Pixel998)
• a086359 维护：移除冗余的 fast-glob 开发依赖 (#20301) (루밀LuMir)
• 564b302 维护：安装 prettier 作为开发依赖 (#20302) (michael faith)
• 8257b57 重构：修正 eslint-plugin/report-message-format 规则的正则表达式 (#20300) (루밀LuMir)
• e251671 重构：提取 RuleTester 中的断言逻辑 (#20135) (唯然)
• 2e7f25e 维护：在 .npmrc 中添加 legacy-peer-deps 配置 (#20281) (Milos Djermanovic)
• 39c638a 维护：为 v10 预发布版本更新 eslint-config-eslint 依赖 (#20278) (Milos Djermanovic)
• 8533b3f 维护：将 @eslint/json 依赖升级至 ^0.14.0 (#20288) (renovate [bot])
• 796ddf6 维护：将 @eslint/js 依赖升级至 ^9.39.1 (#20285) (renovate [bot])