Migrating to v4.0.0

迁移到v4.0.0

ESLint v4.0.0是第四个主要版本发布。我们在这个版本中做了几次重大改变；但是，我们预计大部分更改只会影响很小一部分用户。本指南旨在引导您完成这些更改。

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

对用户来说的重大变化

新规则已被添加到 eslint:recommended

2. indent规则是更加严格

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

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

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

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

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

8. 现在需要在配置文件中引用范围插件来包含范围

打破插件/自定义规则开发人员的更改

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

2. AST节点不再具有注释属性

3. LineComment并且BlockComment在AST遍历期间将不再发生事件

4. Shebang现在从评论API返回

对集成开发人员的突破性更改

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

2. 现在更多报告消息具有完整的位置范围

3. 一些暴露的API现在是ES2015类

eslint:recommended 变化

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

no-compare-neg-zero 不允许比较 -0

no-useless-escape 不允许字符串和正则表达式中无用的转义字符

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

{
  "extends": "eslint:recommended",

  "rules": {
    "no-compare-neg-zero": "off",
    "no-useless-escape": "off"
  }
}

indent规则是更加严格

以前，这个indent规则在检查缩进方面相当宽松；有许多代码模式的缩进未被规则验证。这给用户造成了困惑，因为他们意外地写了带有不正确缩进的代码，他们希望ESLint能够解决问题。

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

为了简化升级过程，我们将indent-legacy规则引入了indent3.x 规则的快照。如果indent升级时遇到规则中的问题，则应该可以使用indent-legacy规则来复制3.x行为。但是，该indent-legacy规则已被弃用，并且将来不会收到错误修正或改进，所以最终应该切换回indent规则。

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

{
  rules: {
    indent: "off",
    "indent-legacy": "error" // replace this with your previous `indent` configuration
  }
}

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

在创建配置时，用户有时会出现拼写错误或误解应该如何配置配置。以前，ESLint没有验证配置文件的属性，所以配置中的拼写错误可能非常繁琐，无法调试。从4.0.0开始，如果配置文件中的属性无法识别或者类型错误，ESLint会引发错误。

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

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

由于bug，.eslintignore文件中的全局模式先前是从进程的当前工作目录中解析出来的，而不是.eslintignore文件的位置。从4.0开始，.eslintignore文件中的模式将从.eslintignore文件的位置解析。

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

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

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

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

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

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

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

{
  "rules": {
    "space-before-function-paren": ["error", {
      "anonymous": "always",
      "named": "always",
      "asyncArrow": "ignore"
    }]
  }
}

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

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

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

{
  "rules": {
    "no-multi-spaces": ["error", {"ignoreEOLComments": true}]
  }
}

现在需要在配置文件中引用范围插件来包含范围

在3.x中，存在一个错误，其中作为配置文件插件的作用域NPM包的引用可能会忽略该作用域。例如，在3.x中，以下配置是合法的：

{
  "plugins": [
    "@my-organization/foo"
  ],
  "rules": {
    "foo/some-rule": "error"
  }
}

换句话说，有可能在foo/some-rule不明确声明@my-organization范围的情况下引用范围插件（如）的规则。这是一个错误，因为如果还有一个同时被称为eslint-plugin-foo加载的非范围插件，它可能会导致模糊的规则引用。

为避免这种歧义，在4.0范围内插件的引用必须包含范围。上面的配置应该固定为：

{
  "plugins": [
    "@my-organization/foo"
  ],
  "rules": {
    "@my-organization/foo/some-rule": "error"
  }
}

要解决的问题：如果您在配置文件中将范围扩展的NPM软件包作为插件引用，请确保将范围包含在引用它的位置。

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

从4.0开始，RuleTester实用程序将验证测试用例对象的属性，并且如果遇到未知属性，则会引发错误。之所以增加这个改变，是因为我们发现开发人员在规则测试中进行拼写错误是相对常见的，通常会使测试用例试图做出的断言失效。

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

AST节点不再有注释属性

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

在4.0中，我们已经摆脱了评论附件的概念，并将所有注释处理逻辑移入ESLint本身。这应该更容易开发定制的解析器，但它也意味着，AST节点将不再有leadingComments和trailingComments性能。从概念上讲，规则制定者现在可以在标记的上下文中而不是AST节点上考虑注释。

为了解决：如果你有依赖于自定义规则leadingComments或trailingComments一个AST节点的属性，你现在可以使用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 }选项取代

LineComment和BlockComment在AST遍历期间将不再发生事件

开始在4.0，LineComment和BlockComments事件不会AST遍历期间发射。有两个原因：

这种行为依赖于在解析器级别发生的评论附件，而这一切都不再发生，以确保所有评论都被解释

在令牌的上下文中考虑评论比在AST节点的背景下考虑评论令牌更容易预测并且更容易推理

为了解决：不是依靠LineComment和BlockComment，规则现在可以使用sourceCode.getAllComments()获得文件中的所有注释。要检查特定类型的所有评论，规则可以使用以下模式：

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

Shebang现在从评论API返回

在4.0之前，源文件中的shebang注释不会出现在sourceCode.getAllComments()or 的输出中sourceCode.getComments()，但它们将sourceCode.getTokenOrCommentBefore作为行注释的输出出现。这种不一致导致了规则制定者的一些混淆。

在4.0中，shebang注释被视为类型的注释标记，Shebang并将由任何SourceCode返回评论的方法返回。这个变化的目标是让shebang的评论与其他标记的处理更加一致。

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

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

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

以前，linter.verify()API接受了一个global配置选项，它是文档globals属性的同义词。global选项从来没有记录或官方支持，并没有在配置文件中工作。它已在4.0中删除。

要解决：如果您使用的是global属性，请使用该globals属性，而不是相同的事情。

现在更多报告消息具有完整的位置范围

在3.1.0开始，规则已经能够指定结束一个报告的问题的位置，除了起始位置，通过在明确指定的结束位置report调用。这对编辑器集成等工具非常有用，它可以使用范围来精确显示报告的问题发生的位置。从4.0开始，如果报告节点而不是位置，则范围的结束位置将自动从节点的结束位置推断。因此，更多报道的问题将会有终端位置。

这不会造成破损。但是，它可能会导致比以前更大的报告位置。例如，如果规则报告AST的根节点，报告的问题范围将是整个程序。在某些集成中，这可能会导致较差的用户体验（例如，如果整个程序突出显示出错误）。

解决方法：如果您的集成处理报告问题的范围，请确保以用户友好的方式处理大型报告范围。

一些暴露的API现在是ES2015类

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

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