迁移到 v4.0.0

ESLint v4.0.0 是第四个主要版本发布。我们在此版本中进行了一些重大更改；但是，我们预计大多数更改只会影响非常小比例的用户。本指南旨在引导您了解这些更改。

以下列表大致按每个更改预计影响的用户数量排序，其中第一个项目预计影响的用户最多。

用户的重大更改

新规则已添加到 eslint:recommended
indent 规则更加严格
配置文件中无法识别的属性现在会导致致命错误
.eslintignore 模式现在从文件位置解析
padded-blocks 规则默认情况下更加严格
space-before-function-paren 规则默认情况下更加严格
no-multi-spaces 规则默认情况下更加严格
配置文件中对作用域插件的引用现在必须包含作用域

插件/自定义规则开发者的重大更改

RuleTester 现在验证测试用例的属性
AST 节点不再具有 comment 属性
AST 遍历期间将不再发出 LineComment 和 BlockComment 事件
Shebang 现在从注释 API 返回

集成开发者的重大更改

linter.verify() API 中的 global 属性不再受支持
更多报告消息现在具有完整的位置范围
一些公开的 API 现在是 ES2015 类

`eslint:recommended` 更改

已将两个新规则添加到 eslint:recommended 配置

no-compare-neg-zero 禁止与 -0 进行比较
no-useless-escape 禁止在字符串和正则表达式中不必要地转义字符

要解决： 要模仿 3.x 中的 eslint:recommended 行为，您可以在配置文件中禁用这些规则

{
  "extends": "eslint:recommended",

  "rules": {
    "no-compare-neg-zero": "off",
    "no-useless-escape": "off"
  }
}
1
2
3
4
5
6
7
8

`indent` 规则更加严格

以前，indent 规则在检查缩进方面相当宽松；在许多代码模式中，缩进未通过该规则验证。这给用户造成了困惑，因为他们意外地编写了缩进不正确的代码，并且他们期望 ESLint 能够捕获这些问题。

在 4.0.0 中，indent 规则已重写。新版本的规则将报告旧版本的规则未捕获的一些缩进错误。此外，默认情况下现在将检查 MemberExpression 节点、函数参数和函数参数的缩进（以前为了向后兼容性而默认忽略）。

为了使升级过程更容易，我们引入了 indent-legacy 规则作为 3.x 中 indent 规则的快照。如果您在升级时遇到 indent 规则的问题，您应该能够使用 indent-legacy 规则来复制 3.x 行为。但是，indent-legacy 规则已弃用，并且将来不会收到错误修复或改进，因此您最终应该切换回 indent 规则。

要解决： 我们建议在不更改 indent 配置的情况下进行升级，并修复代码库中出现的任何新的缩进错误。但是，如果您想模仿 indent 规则在 3.x 中的工作方式，您可以更新您的配置

{
  rules: {
    indent: "off",
    "indent-legacy": "error" // replace this with your previous `indent` configuration
  }
}
1
2
3
4
5
6

配置文件中无法识别的属性现在会导致致命错误

创建配置时，用户有时会拼写错误或误解配置的结构方式。以前，ESLint 不验证配置文件的属性，因此配置中的拼写错误可能很难调试。从 4.0.0 开始，如果配置文件中的属性无法识别或类型错误，ESLint 将引发错误。

要解决： 如果您在升级后看到配置验证错误，请验证您的配置是否不包含任何拼写错误。如果您正在使用无法识别的属性，您应该能够从您的配置中删除它以恢复以前的行为。

.eslintignore 模式现在从文件位置解析

由于一个错误，.eslintignore 文件中的 glob 模式以前是从进程的当前工作目录而不是 .eslintignore 文件的位置解析的。从 4.0 开始，.eslintignore 文件中的模式将从 .eslintignore 文件的位置解析。

要解决： 如果您使用 .eslintignore 文件并且您经常从项目根目录以外的其他位置运行 ESLint，则模式可能会以不同的方式匹配。您应该更新 .eslintignore 文件中的模式，以确保它们相对于文件而不是工作目录。

`padded-blocks` 规则默认情况下更加严格

默认情况下，padded-blocks 规则现在将在类体和 switch 语句中强制执行填充。以前，该规则会忽略这些情况，除非用户选择强制执行它们。

要解决： 如果此更改导致您的代码库中出现更多 linting 错误，您应该修复它们或重新配置规则。

`space-before-function-paren` 规则默认情况下更加严格

默认情况下，space-before-function-paren 规则现在将为 async 箭头函数强制执行间距。以前，该规则会忽略这些情况，除非用户选择强制执行它们。

要解决： 要模仿 3.x 中的默认配置，您可以使用

{
  "rules": {
    "space-before-function-paren": ["error", {
      "anonymous": "always",
      "named": "always",
      "asyncArrow": "ignore"
    }]
  }
}
1
2
3
4
5
6
7
8
9

`no-multi-spaces` 规则默认情况下更加严格

默认情况下，no-multi-spaces 规则现在将禁止在一行末尾的注释前出现多个空格。以前，该规则不检查这种情况。

要解决： 要模仿 3.x 中的默认配置，您可以使用

{
  "rules": {
    "no-multi-spaces": ["error", {"ignoreEOLComments": true}]
  }
}
1
2
3
4
5

配置文件中对作用域插件的引用现在必须包含作用域

在 3.x 中，存在一个错误，即在配置文件中将作用域 NPM 包作为插件的引用可以省略作用域。例如，在 3.x 中，以下配置是合法的

{
  "plugins": [
    "@my-organization/foo"
  ],
  "rules": {
    "foo/some-rule": "error"
  }
}
1
2
3
4
5
6
7
8

换句话说，可以引用来自作用域插件（例如 foo/some-rule）的规则，而无需显式声明 @my-organization 作用域。这是一个错误，因为它可能导致模糊的规则引用，如果同时加载了也称为 eslint-plugin-foo 的非作用域插件。

为了避免这种歧义，在 4.0 中，对作用域插件的引用必须包含作用域。上面的配置应修复为

{
  "plugins": [
    "@my-organization/foo"
  ],
  "rules": {
    "@my-organization/foo/some-rule": "error"
  }
}
1
2
3
4
5
6
7
8

要解决： 如果您在配置文件中将作用域 NPM 包作为插件引用，请务必在引用它的任何地方包含作用域。

`RuleTester` 现在验证测试用例的属性

从 4.0 开始，RuleTester 实用程序将验证测试用例对象的属性，如果遇到未知属性，将抛出错误。添加此更改是因为我们发现开发人员在规则测试中拼写错误相对常见，这通常会使测试用例尝试进行的断言无效。

要解决： 如果您的自定义规则的测试具有额外的属性，您应该删除这些属性。

AST 节点不再具有 comment 属性

在 4.0 之前，ESLint 要求解析器实现注释附加，这是一个 AST 节点将获得与其在源文件中的前导和尾随注释相对应的附加属性的过程。这使得用户难以开发自定义解析器，因为他们必须复制 ESLint 要求的令人困惑的注释附加语义。

在 4.0 中，我们已经放弃了注释附加的概念，并将所有注释处理逻辑移至 ESLint 本身。这应该使开发自定义解析器更容易，但这也意味着 AST 节点将不再具有 leadingComments 和 trailingComments 属性。从概念上讲，规则作者现在可以在标记的上下文中而不是 AST 节点的上下文中考虑注释。

要解决： 如果您的自定义规则依赖于 AST 节点的 leadingComments 或 trailingComments 属性，您现在可以分别使用 sourceCode.getCommentsBefore() 和 sourceCode.getCommentsAfter() 来代替。

此外，sourceCode 对象现在还具有 sourceCode.getCommentsInside()（返回节点内的所有注释）、sourceCode.getAllComments()（返回文件中的所有注释），并允许通过各种其他标记迭代器方法（例如 getTokenBefore() 和 getTokenAfter()）以及 { includeComments: true } 选项访问注释。

对于除了 v4.0 之外还担心支持 ESLint v3.0 的规则作者，现在已弃用的 sourceCode.getComments() 仍然可用，并且适用于这两个版本。

最后，请注意以下 SourceCode 方法已被弃用，并将在 ESLint 的未来版本中删除

getComments() - 由 getCommentsBefore()、getCommentsAfter() 和 getCommentsInside() 替换
getTokenOrCommentBefore() - 由 getTokenBefore() 和 { includeComments: true } 选项替换
getTokenOrCommentAfter() - 由 getTokenAfter() 和 { includeComments: true } 选项替换

AST 遍历期间将不再发出 `LineComment` 和 `BlockComment` 事件

从 4.0 开始，AST 遍历期间将不会发出 LineComment 和 BlockComments 事件。有两个原因

此行为依赖于在解析器级别发生的注释附加，而现在不再发生这种情况，以确保所有注释都将被考虑在内。
在标记的上下文中考虑注释比在 AST 节点的上下文中考虑注释标记更可预测且更易于推理。

要解决： 规则现在可以使用 sourceCode.getAllComments() 来获取文件中的所有注释，而不是依赖于 LineComment 和 BlockComment。要检查特定类型的所有注释，规则可以使用以下模式

sourceCode.getAllComments().filter(comment => comment.type === "Line");
sourceCode.getAllComments().filter(comment => comment.type === "Block");
1
2

Shebang 现在从注释 API 返回

在 4.0 之前，源文件中的 shebang 注释不会出现在 sourceCode.getAllComments() 或 sourceCode.getComments() 的输出中，但它们会作为行注释出现在 sourceCode.getTokenOrCommentBefore 的输出中。这种不一致导致了一些规则开发者的困惑。

在 4.0 中，shebang 注释被视为 Shebang 类型的注释标记，并将由任何返回注释的 SourceCode 方法返回。此更改的目标是使 shebang 注释的处理方式与其他标记的处理方式更加一致。

要解决： 如果您的自定义规则对注释执行操作，则可能需要一些额外的逻辑来确保正确处理或过滤掉 shebang 注释

sourceCode.getAllComments().filter(comment => comment.type !== "Shebang");
1

`linter.verify()` API 中的 `global` 属性不再受支持

以前，linter.verify() API 接受一个 global 配置选项，它是已记录的 globals 属性的同义词。global 选项从未记录或正式支持，并且在配置文件中不起作用。它已在 4.0 中删除。

要解决： 如果您正在使用 global 属性，请改用 globals 属性，它的作用相同。

一些公开的 API 现在是 ES2015 类

来自 ESLint 的 Node.js API 的 CLIEngine、SourceCode 和 RuleTester 模块现在是 ES2015 类。这不会破坏任何已记录的行为，但它确实有一些可观察到的影响（例如，CLIEngine.prototype 上的方法现在是不可枚举的）。

要解决： 如果您依赖于枚举 ESLint 的 Node.js API 的方法，请使用一个也可以访问不可枚举属性的函数，例如 Object.getOwnPropertyNames。

编辑此页

迁移到 v4.0.0

用户的重大更改

插件/自定义规则开发者的重大更改

集成开发者的重大更改

eslint:recommended 更改

indent 规则更加严格

配置文件中无法识别的属性现在会导致致命错误

.eslintignore 模式现在从文件位置解析

padded-blocks 规则默认情况下更加严格

space-before-function-paren 规则默认情况下更加严格

no-multi-spaces 规则默认情况下更加严格