
亮点
🌐 Highlights
ESLint v10.0.0 是一个重大版本,包含了若干新功能和重大更改。以下是一些最显著的更新内容。
🌐 ESLint v10.0.0 is a major release that includes several new features and breaking changes. Here are some of the most notable updates.
正在安装
🌐 Installing
因为这是一个重大版本发布,你可能不会被 npm 自动升级。为了确保你使用的是此版本,请运行:
🌐 Because this is a major release, you may not automatically be upgraded by npm. To ensure you are using this version, run:
npm i eslint@10.0.0 --save-dev
不再支持 Node.js < v20.19.0、v21.x、v23.x
🌐 Node.js < v20.19.0, v21.x, v23.x no longer supported
截至本帖发布,Node.js v24.x 是 LTS 版本,因此我们将停止支持所有早于 v20.19.0 的 Node.js 版本以及 v21.x 和 v23.x。
🌐 As of this post, Node.js v24.x is the LTS release, and as such we are dropping support for all versions of Node.js prior to v20.19.0 as well as v21.x and v23.x.
迁移指南
🌐 Migration Guide
由于有很多变化,我们创建了一个 迁移指南,详细描述了重大更改以及你应该采取的应对步骤。我们预计大多数用户应该能够在不更改构建的情况下升级,但如果遇到问题,迁移指南应该是一个有用的资源。
🌐 As there are a lot of changes, we’ve created a migration guide describing the breaking changes in great detail along with the steps you should take to address them. We expect that most users should be able to upgrade without any build changes, but the migration guide should be a useful resource if you encounter problems.
新的配置文件查找算法
🌐 New configuration file lookup algorithm
ESLint v10.0.0 通过从每个被 lint 的文件的目录开始定位 eslint.config.*,而不是像 ESLint v9.x 那样使用当前工作目录。新的行为允许在同一次运行中使用多个配置文件,并且在 monorepo 设置中尤其有用。
🌐 ESLint v10.0.0 locates eslint.config.* by starting from the directory of each linted file rather than the current working directory as was the case with ESLint v9.x. The new behavior allows for using multiple configuration files in the same run and can be particularly useful in monorepo setups.
在 ESLint v9.x 中,这种配置查找行为可以通过 v10_config_lookup_from_file 功能标志启用。在 ESLint v10.0.0 中,这种行为现在是默认的,并且 v10_config_lookup_from_file 标志已被移除。
🌐 In ESLint v9.x, this config lookup behavior could be enabled with the v10_config_lookup_from_file feature flag. In ESLint v10.0.0, this behavior is now the default and the v10_config_lookup_from_file flag has been removed.
已移除 eslintrc 功能
🌐 Removed eslintrc functionality
正如在 Flat 配置推出计划中宣布的,eslintrc 配置系统已在 ESLint v10.0.0 中被完全移除。具体来说,这意味着:
🌐 As announced in Flat config rollout plans, the eslintrc config system has been completely removed in ESLint v10.0.0. Specifically, this means:
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"会抛出错误。- 以下
Lintereslintrc 特定的方法已被移除:defineParser()defineRule()defineRules()getRules()
- 对
/use-at-your-own-risk入口点的以下更改:LegacyESLint已被移除FileEnumerator已被移除shouldUseFlatConfig()函数将始终返回true
JSX 引用现在已被跟踪
🌐 JSX references are now tracked
ESLint v10.0.0 现在跟踪 JSX 引用,从而能够正确分析 JSX 元素的作用域。
🌐 ESLint v10.0.0 now tracks JSX references, enabling correct scope analysis of JSX elements.
以前,JSX 标识符不会被追踪为引用,这可能导致依赖作用域信息的规则产生不正确的结果。例如:
🌐 Previously, JSX identifiers weren’t tracked as references, which could lead to incorrect results in rules relying on scope information. For example:
import { Card } from "./card.jsx";
export function createCard(name) {
return <Card name={name} />;
}
在 v10.0.0 之前:
🌐 Prior to v10.0.0:
- 误报:
<Card>可能会被报告为“已定义但从未使用” (no-unused-vars)。 - 假阴性:移除导入可能不会触发“未定义变量”错误 (
no-undef)。
从 v10.0.0 开始,<Card> 被视为对作用域内变量的普通引用。这消除了令人困惑的误报/漏报,使 JSX 处理符合开发者的预期,并改善了使用 JSX 的项目中的代码检查体验。
🌐 Starting with v10.0.0, <Card> is treated as a normal reference to the variable in scope. This eliminates confusing false positives/negatives, aligns JSX handling with developer expectations, and improves the linting experience in projects using JSX.
Espree 和 ESLint Scope 现在包括类型
🌐 Espree and ESLint Scope now include types
从 Espree v11.1.0 和 ESLint Scope v9.1.0 开始,这些包现在包含内置类型定义。
🌐 Beginning with Espree v11.1.0 and ESLint Scope v9.1.0, these packages now contain built-in type definitions.
以前,类型定义由 Definitely Typed 包 @types/espree 和 @types/eslint-scope 提供。旧类型定义和新类型定义之间有一些差异,主要是错误修复。如果你的代码依赖于 Espree 和 ESLint Scope 包的类型,请检查是否需要进行任何更新。
🌐 Previously, type definitions were provided by Definitely Typed packages @types/espree and @types/eslint-scope. There are several differences between the old and new type definitions, mostly bug fixes. If your code relies on types for the Espree and ESLint Scope packages, check if there are any updates needed.
RuleTester 的增强功能
🌐 Enhancements to RuleTester
自最早期以来,ESLint 就提供了 RuleTester API,帮助插件作者针对自定义测试案例和配置测试他们的规则。本次发布对 RuleTester 进行了若干增强,以执行更强健的测试定义并改进调试。
🌐 Since its earliest days, ESLint has provided the RuleTester API to help plugin authors test their rules against custom test cases and configurations. This release introduces several enhancements to RuleTester to enforce more robust test definitions and improve debugging.
断言选项
🌐 Assertion options
RuleTester#run() 方法现在支持 断言选项,具体包括 requireMessage、requireLocation 和 requireData,以便开发者在规则测试中执行更严格的要求。这些选项强制每个无效测试用例显式检查违规消息、位置和数据,确保如果测试不符合要求就会失败。
🌐 The RuleTester#run() method now supports assertion options, specifically requireMessage, requireLocation, and requireData, to let developers enforce stricter requirements in rule tests. These options enforce that every invalid test case explicitly checks violation messages, locations, and data, ensuring that a test fails if it doesn’t meet the requirements.
requireMessage- 确保每个测试用例都包含消息检查。
- 接受:
true:必须使用对象数组作为errors,而不是数字计数简写,以检查规则报告的问题。每个对象必须像往常一样包含message或messageId属性,以检查报告问题的消息。"message":必须仅使用message进行检查。"messageId":必须仅使用messageId进行检查。
- 目的: 防止测试在未验证实际消息的情况下通过。
requireLocation- 确保每个测试用例都包括位置检查。
- 接受:
true - 在
errors数组的每个对象中需要line和column。 endLine和endColumn是可选的,如果实际报告中不包括它们。- 目的: 保证测试能够验证错误的位置。
requireData- 确保每个测试用例都包含一个
data检查。 - 接受:
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
}
});
改进了失败测试的位置信息报告
🌐 Improved location reporting for failing tests
RuleTester 现在会在堆栈跟踪中添加信息,使你更容易在源代码中定位失败的测试用例。例如,测试输出现在将包括堆栈跟踪行,指示失败测试用例在 invalid 数组中的索引以及定义该测试用例的文件和行号。
请注意,这些行号可能并不总是包含在内,这取决于你的测试是如何构建的。当无法精确确定行时,仍然可以使用失败的测试索引和打印的代码片段来定位测试用例。
🌐 Note that these line numbers may not always be included, depending on how your tests are structured. When the lines cannot be determined precisely, the failing test index and the printed code snippet are still available to locate the test case.
max-params 规则中的 countThis 选项
🌐 countThis option in max-params rule
max-params 规则现在支持新的 countThis 选项,该选项取代了已弃用的 countVoidThis。使用 countThis: "never" 设置时,该规则在计算 TypeScript 函数的参数数量时,将忽略函数参数列表中的任何 this 注解。例如:
🌐 The max-params rule now supports the new countThis option, which supersedes the deprecated countVoidThis. With the setting countThis: "never", the rule will now ignore any this annotation in a function’s argument list when counting the number of parameters in a TypeScript function. For example:
function doSomething(this: SomeType, first: string, second: number) {
// ...
}
将被视为一个只接受两个参数的函数。
🌐 will be considered a function taking only 2 parameters.
格式化器上下文中的 color 属性
🌐 color property in formatter context
当在命令行上指定 --color 或 --no-color 选项时,ESLint 会在传递给格式化器的上下文对象(format() 方法的第二个参数)上设置一个额外的 color 属性。对于 --color,该属性为 true;对于 --no-color,该属性为 false。自定义格式化器 可以使用该值来确定是否应用颜色样式,假设终端支持或不支持颜色,如该选项所示。
🌐 When the --color or --no-color option is specified on the command line, ESLint sets an additional color property on the context object passed to a formatter (the second argument of the format() method). This property is true for --color and false for --no-color. Custom formatters can use this value to determine whether to apply color styling, based on the assumption that the terminal supports or does not support colors as indicated by the option.
已更新 eslint:recommended
🌐 Updated eslint:recommended
eslint:recommended 配置已更新以包含我们认为重要的新规则。
🌐 The eslint:recommended configuration is updated to include new rules that we feel are important.
已移除已弃用的规则 context 成员
🌐 Removed deprecated rule context members
以下规则 context 的成员不再可用:
🌐 The following rule context members are no longer available:
context.getCwd()- 请改用context.cwdcontext.getFilename()- 请改用context.filenamecontext.getPhysicalFilename()- 请改用context.physicalFilenamecontext.getSourceCode()- 请改用context.sourceCodecontext.parserOptions- 使用context.languageOptions或context.languageOptions.parserOptions替代context.parserPath- 无替换
已移除已弃用的 SourceCode 方法
🌐 Removed deprecated SourceCode methods
以下 SourceCode 方法不再可用:
🌐 The following SourceCode methods are no longer available:
getTokenOrCommentBefore()- 改用带有{ includeComments: true }选项的getTokenBefore()getTokenOrCommentAfter()- 改用带有{ includeComments: true }选项的getTokenAfter()isSpaceBetweenTokens()- 请改用isSpaceBetween()getJSDocComment()- 无替换
Program AST 节点范围覆盖整个源文本
🌐 Program AST node range spans entire source text
从 ESLint v10.0.0 开始,Program AST 节点的范围覆盖整个源文本。之前,前导和尾随的注释/空白不包括在范围内。
🌐 Starting with ESLint v10.0.0, Program AST node’s range spans the entire source text. Previously, leading and trailing comments/whitespace were not included in the range.
Jiti < v2.2.0 不再支持
🌐 Jiti < v2.2.0 no longer supported
ESLint v10.0.0 在加载 TypeScript 配置文件时不再支持 jiti 2.2.0 之前的版本,因为已知问题可能导致在加载某些插件时出现兼容性问题。
🌐 ESLint v10.0.0 drops support for jiti versions prior to 2.2.0 when loading TypeScript configuration files due to known issues that can cause compatibility problems when configurations load certain plugins.
重大更改
🌐 Breaking Changes
f9e54f4功能更新!: 估算规则测试失败位置 (#20420) (ST-DDT)a176319功能更新!: 将chalk替换为styleText并将color添加到ResultsMeta(#20227) (루밀LuMir)c7046e6功能更新!: 启用 JSX 引用跟踪 (#20152) (Pixel998)fa31a60增强功能!: 将name添加到配置 (#20015) (Kirk Waiblinger)3383e7e修复!: 移除已弃用的SourceCode方法 (#20137) (Pixel998)501abd0重大更新!: 将依赖 minimatch 更新到 v10 (#20246) (renovate[bot])ca4d3b4修复!: 对有效测试用例的更严格规则测试断言 (#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功能更新!: 程序范围遍及整个源文本 (#20133) (Pixel998)39a6424修复!: 确保在所有 RuleFixer 方法中 ‘text’ 是字符串 (#20082) (Pixel998)f28fbf8修复!: 弃用radix规则的"always"和"as-needed"选项 (#20223) (Milos Djermanovic)aa3fb2b修复!: 收紧func-names模式 (#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功能:规则测试器添加断言选项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文档:更新自述文件(GitHub Actions 机器人)4cecf83文档:更新自述文件(GitHub Actions 机器人)c79f0ab文档:更新自述文件(GitHub Actions 机器人)773c052文档:更新自述文件(GitHub Actions 机器人)f2962e4文档:文档meta.docs.frozen属性 (#20475) (Pixel998)8e94f58文档:修复因动名词标题更新而导致的断开锚点链接 (#20449) (Copilot)1495654文档:更新自述文件(GitHub Actions 机器人)0b8ed5c文档::is选择器别名的文档支持 (#20454) (sethamus)1c4b33f文档:关于仅 ESM 依赖的文档策略 (#20448) (Milos Djermanovic)3e5d38c文档:在规则示例中添加缺失的缩进空格 (#20446) (fnx)63a0c7c文档:更新自述文件(GitHub Actions 机器人)65ed0c9文档:更新自述文件(GitHub Actions 机器人)b0e4717文档: [no-await-in-loop] 扩展不适用性 (#20363) (Niklas Hambüchen)fca421f文档:更新自述文件(GitHub Actions 机器人)d925c54文档:更新no-lone-blocks中的配置语法 (#20413) (Pixel998)7d5c95f文档:从规则示例中删除多余的sourceType: "module"(#20412) (Pixel998)02e7e71文档:修复带有扩展名示例文件中的.mts通配符模式 (#20403) (Ali Essalihi)264b981文档:更新自述文件(GitHub Actions 机器人)5a4324f文档:澄清no-unused-vars的"local"选项 (#20385) (Milos Djermanovic)e593aa0文档:提高文档网站 README 的清晰度、语法和措辞 (#20370) (Aditya)3f5062e文档:在规则元数据文档中添加 messages 属性 (#20361) (Sabya Sachi)9e5a5c2文档:从规则文档中删除Examples标题 (#20364) (Milos Djermanovic)194f488文档:更新自述文件(GitHub Actions 机器人)0f5a94a文档:[class-methods-use-this] 解释规则的目的 (#20008) (Kirk Waiblinger)df5566f文档:为所有规则文档添加选项部分 (#20296) (sethamus)adf7a2b文档: no-unsafe-finally 对生成器函数的注释 (#20330) (Tom Pereira)ef7028c文档:更新自述文件(GitHub Actions 机器人)fbae5d1文档:在迁移指南中始终使用 “v10.0.0” (#20328) (Pixel998)778aa2d文档:忽略默认文件模式 (#20312) (Tanuj Kanti)4b5dbcd文档:重排 v10 迁移指南 (#20315) (Milos Djermanovic)5d84a73文档:更新自述文件(GitHub Actions 机器人)37c8863文档:修复 v10 迁移指南中的错误锚点链接 (#20299) (Pixel998)077ff02文档:添加迁移到 10.0.0 文档 (#20143) (唯然)3822e1b文档:更新自述文件(GitHub Actions 机器人)
构建相关
🌐 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)034e139ci: 为@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)11644b1ci:重命名工作流 (#20463) (Milos Djermanovic)2d14173任务:修复文档和注释中的拼写错误 (#20458) (o-m12a)6742f92测试:在 no-alert 的无效测试用例中添加 endLine/endColumn (#20441) (경하)3e22c82测试:向 no-template-curly-in-string 测试中添加缺失的位置信息 (#20440) (Haeun Kim)b4b3127事务:更新 package.json 以适配 @eslint/js 版本发布(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)54bf0a3ci:创建包管理器测试 (#20392) (루밀LuMir)3115021重构:简化 JSDoc 注释检测逻辑 (#20360) (Pixel998)4345b17事务: 将@eslint-community/regexpp更新为4.12.2(#20366) (루밀LuMir)772c9ee事务: 更新依赖 @eslint/eslintrc 到 ^3.3.3 (#20359) (renovate[bot])0b14059事务:更新 package.json 以适配 @eslint/js 版本发布(Jenkins)d6e7bf3ci:将 actions/checkout 从 5 升级到 6 (#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事务:更新 package.json 以适配 @eslint/js 版本发布(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杂务:将legacy-peer-deps添加到.npmrc(#20281) (Milos Djermanovic)39c638a杂务:更新 eslint-config-eslint 依赖以支持 v10 预发布版本 (#20278) (Milos Djermanovic)8533b3f杂项:将依赖 @eslint/json 更新到 ^0.14.0 (#20288) (renovate[bot])796ddf6杂项:将依赖 @eslint/js 更新到 ^9.39.1 (#20285) (renovate[bot])
