[译] ESLint v4.0.0 升级指南

• 原文地址：ESLint Migrating to v4.0.0
• 原文做者：ESLint
• 译文出自：掘金翻译计划
• 译者：吃土小2叉
• 校对者：薛定谔的猫、sqrthree

ESLint v4.0.0 升级指南

ESLint v4.0.0 是 ESLint 的第 4 个主版本。固然，咱们但愿大多数变动只影响极少数用户。本文旨在帮助您了解具体有哪些更改。

如下列表大体按每一个更改可能影响的用户数量进行排序，排序越靠前影响的用户数越多。

ESLint 使用者请注意

1. eslint:recommended 新增规则
2. indent 规则将更严格
3. 如今配置文件中未识别的属性会报告严重错误
4. 忽略文件将从 .eslintignore 文件所在目录开始解析
5. 默认状况下 padded-blocks 规则将更严格
6. 默认状况下 space-before-function-paren 规则将更严格
7. 默认状况下 no-multi-spaces 规则将更严格
8. 如今必须包含命名空间，才能引用限定在命名空间下的插件

ESLint 插件开发者和自定义规则开发者请注意

1. 如今 RuleTester 将验证测试用例对象的属性
2. AST 节点再也不具备注释属性
3. 在 AST 遍历期间不会触发 LineComment 和 BlockComments 事件
4. 如今 Shebang 能够经过注释 API 返回

集成开发者请注意

1. linter.verify() API 再也不支持 global 属性
2. 如今更多报告消息具备完整的位置范围
3. 部分暴露的 API 将使用 ES2015 中的类

---

eslint:recommended 新增规则

eslint:recommended 中新增了两条规则：

• no-compare-neg-zero 不容许与 -0 进行比较
• no-useless-escape 不容许在字符串和正则表达式中使用无心义的换行符

注: 若是要与 ESLint 3.x 的 eslint:recommended 保持一致，您能够在配置文件中禁用上述规则：

{
  "extends": "eslint:recommended",

  "rules": {
    "no-compare-neg-zero": "off",
    "no-useless-escape": "off"
  }
}复制代码

indent 规则将更严格

过去的 indent 规则在检查缩进方面是至关宽容的：过去的缩进校验规则会忽略许多代码模式。而这会让用户产生困扰，由于他们偶尔会有不正确的代码缩进，而且他们本指望 ESLint 可以发现这些问题（译者补充：然而并无发现）。

在 ESLint v4.0.0 中，indent 规则被重写。新版规则将报告出旧版规则没法发现的缩进错误。另外，MemberExpression 节点、函数声明参数以及函数调用参数将默认进行缩进检查（过去为了向后兼容，这些默认都被忽略了）。

为了方便升级到 ESLint 4.0.0，咱们引入了 indent-legacy 规则做为 ESLint 3.x 中 indent 规则的快照。若是你在升级过程当中遇到了 indent 规则的相关问题，那么您能够借助于 indent-legacy 规则来维持与 3.x 一致。然而，indent-legacy 规则已被弃用而且在未来再也不维护，因此您最终仍是应该使用 indent 规则。

注： 推荐在升级过程当中不要更改 indent 配置，并修正新的缩进错误。然而若是要与 ESLint 3.x 的 indent 规则保持一致，您能够这样配置：

{
  rules: {
    indent: "off",
    "indent-legacy": "error" // 用以前的 `indent` 配置替换此处
  }
}复制代码

如今配置文件中未识别的属性会报告严重错误

在建立配置文件时，用户有时候会犯拼写错误或者弄错配置文件的结构。在之前，ESLint 并不会验证配置文件中的属性，所以很难调试配置文件中的拼写错误。而从 ESLint v4.0.0 起，当配置文件中存在未识别的属性或者属性类型有错误时，ESLint 会抛出一个错误。

注： 升级后若是发现配置文件验证出错，请检查配置文件中是否存在拼写错误。若是使用了未识别的属性，那么应该将之从配置文件中移除，从而使 ESLint 恢复正常。

忽略文件将从 .eslintignore 文件所在目录开始解析

过去因为一个 bug，.eslintignore 文件的路径名模板是从进程的当前工做目录解析，而不是 .eslintignore 文件的位置。从 ESLint 4.0 开始，.eslintignore 文件的路径名模板将从 .eslintignore 文件的位置解析。

注： 若是您使用 .eslintignore 文件，而且您常常从项目根目录之外的地方运行 ESLint，则可能会以不一样的模式匹配路径名。您应该更新 .eslintignore 文件中的匹配模式，以确保它们与该文件相关，而不是与工做目录相关。

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

如今默认状况下， padded-blocks 规则要求在类内填充空行以及在 switch 语句中填充空行。而过去除非用户更改配置，不然默认状况下这条规则会忽略上述状况的检查。

注： 若是此更改致使代码库中出现更多的错误，您应该修复它们或从新配置规则。

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

如今默认状况下， space-before-function-paren 规则要求异步箭头函数的圆括号与 async 关键词之间存在空格。而过去除非用户更改配置，不然默认状况下这条规则会忽略对异步箭头函数的检查。

注： 若是要与 ESLint 3.x 的默认配置保持一致，您能够这样配置：

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

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

如今默认状况下， no-multi-spaces 规则禁止行尾注释前存在多个空格。而过去这条规则不对此进行检查。

注： 若是要与 ESLint 3.x 的默认配置保持一致，您能够这样配置：

{
  "rules": {
    "no-multi-spaces": ["error", {"ignoreEOLComments": true}]
  }
}复制代码

如今必须包含命名空间，才能引用限定在命名空间下的插件

在 ESLint 3.x 中存在一个 bug：引用限定在命名空间下的插件可能会忽略该命名空间。举个例子，在 ESLint 3.x 中如下配置是合法的：

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

换句话说，过去能够引用限定命名空间的插件的规则（例如 foo/some-rule），同时无需明确声明 @my-organization 的命名空间。这是一个 bug，由于若是同时加载了一个名为 eslint-plugin-foo 的不限定命名空间的插件，可能会致使引用规则时产生歧义。

为了不歧义，在 ESLint 4.0 中必须包含命名空间，才能引用限定在命名空间下的插件。

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

注： 若是您在配置文件中引用了限定在命名空间下的插件，那么请确保在引用的时候包含命名空间。

---

如今 RuleTester 将验证测试用例对象的属性

从 ESLint 4.0 开始，RuleTester 工具将验证测试用例对象的属性，若是遇到未知属性，将抛出错误。这番改动是由于咱们发现开发人员在测试规则时的拼写错误是比较常见的，且一般会使测试用例试图做出的断言无效。

注： 若是您对自定义规则的测试用例对象具备额外的属性，则应该移除这些属性。

AST 节点再也不具备注释属性

在 ESLint 4.0 以前，ESLint 须要解析器实现附加注释的解析，这个过程当中，AST 节点将从源文件的先后置注释中获取额外的相关联属性。这就使得用户很难去开发自定义解析器，由于他们不得不去重复解析那些使人困惑同时又是 ESlint 必需的附加注释语义。

在 ESLint 4.0 中，咱们已经摆脱了附加注释的概念，并将全部的注释处理逻辑转移到了 ESLint 自己。这样能够更容易地开发自定义解析器，但这也意味着 AST 节点将再也不具备 leadingComments 和 trailingComments 属性。 从概念上来讲，规则做者如今能够在 tokens 上下文而不是 AST 节点的上下文中考虑注释。

注： 若是您有一个依赖于 AST 节点的 leadingComments 或 trailingComments 属性的自定义规则，则能够分别使用 sourceCode.getCommentsBefore() 和 sourceCode.getCommentsAfter() 替代。

此外，sourceCode 对象如今也有 sourceCode.getCommentsInside() 方法（它返回一个节点内的全部注释），sourceCode.getAllComments() 方法（它返回文件中的全部注释），并容许注释经过各类其余 token 迭代器方法（例如 getTokenBefore() 和 getTokenAfter()）并设置选项{includeComments：true} 进行访问。

对于想要同时兼容 ESLint v3.0 和 v4.0 的规则做者，如今已经不推荐使用的 sourceCode.getComments() 仍然可用，而且这两个版本都兼容。

最后请注意，如下 SourceCode 方法已被弃用，将在之后的 ESLint 版本中被移除：

• getComments() - 请使用 getCommentsBefore()、getCommentsAfter() 和 getCommentsInside() 来替换
• getTokenOrCommentBefore() - 请使用 getTokenBefore() 方法并设置选项 {includeComments:true} 来替换
• getTokenOrCommentAfter() - 请使用 getTokenAfter() 方法并设置选项 {includeComments:true} 来替换

在 AST 遍历期间不会触发 LineComment 和 BlockComments 事件

从 ESLint 4.0 开始，在 AST 遍历期间不会触发 LineComment 和 BlockComments 事件。缘由以下：

• 过去这种行为依赖于在解析器级别的注释附属物，而自 ESLint 4.0 开始再也不如此，以确保全部注释将被考虑
• 在 tokens 上下文中考虑注释更容易预测和更容易理解，而非在 AST 节点上下文中考虑注释 token

注： 规则如今可使用sourceCode.getAllComments() 来获取文件中的全部注释，而非依赖于 LineComment 和 BlockComment。要检查特定类型的全部注释，规则可使用如下模式：

sourceCode.getAllComments().filter(comment => comment.type === "Line");
sourceCode.getAllComments().filter(comment => comment.type === "Block");复制代码

如今 Shebang 能够经过注释 API 返回

（译者注：Shebang 是一个由井号和叹号构成的字符序列 #!，其出如今文本文件的第一行的前两个字符。参考：Shebang_(Unix))）

在 ESLint 4.0 以前，源文件中的 shebang 注释不会出如今 sourceCode.getAllComments() 或 sourceCode.getComments() 的输出中，但它们将做为行注释出如今 sourceCode.getTokenOrCommentBefore 的输出中。这种不一致会给规则开发者带来困惑。

在 ESLint 4.0 中，shebang 注释被视为 Shebang 类型的注释 tokens，并能够经过任何返回注释的 SourceCode 方法返回。该变化的目的是为了让 shebang 的评论更符合其余 tokens 的处理方式。

注： 若是您有一个自定义规则对注释执行操做，可能须要一些额外的逻辑来确保 shebang 注释被正确处理或被正常过滤掉：

sourceCode.getAllComments().filter(comment => comment.type !== "Shebang");复制代码

---

linter.verify() API 再也不支持 global 属性

过去，linter.verify() API 接受 global 属性做为一个配置项，它与官方文档中的 globals 做用相同。可是，global 属性从未出如今官方文档中或者被官方支持，而且在配置文件中该属性会失效。自 ESLint 4.0 起，该属性已被移除。

注： 若是您先前使用了 global 属性，请用 globals 属性替换，其做用与 global 相同。

如今更多报告消息具备完整的位置范围

从 ESLint 3.1.0 开始，除了开始位置以外，规则还能够经过调用 report 时明确指定一个结束位置来指定问题报告的结束位置。这对于编辑器集成这样的工具颇有用，可使用范围来精确显示出现问题的位置。从 ESLint 4.0 开始，若是报告了节点而不是一个具体位置，则该结束位置的范围将自动从节点的结束位置推断出来。所以，更多报告的问题将会有结束位置。

这不会带来兼容性问题。然而，这可能会致使比之前更大的报告位置范围。例如，若是一条规则报告的是 AST 的根节点，则问题的范围将是整个程序。在某些集成中，这可能致使用户体验不佳（例如，若是整个程序都被高亮显示以指示错误）。

注： 若是您有处理报告问题范围的集成，请确保以对用户友好的方式处理大型报告范围。

部分暴露的 API 将使用 ES2015 中的类

如今部分 ESLint 的 Node.js API，好比 CLIEngine、SourceCode 以及 RuleTester 模块使用了 ES2015 中的类。固然这不会影响到接口的正常使用，不过这的确会产生一些明显的影响（举个例子，CLIEngine.prototype 将不可枚举）。

注： 若是您须要对 ESLint 的 Node.js API 提供的方法进行枚举遍历，能够用诸如 Object.getOwnPropertyNames 的函数来访问不可枚举属性。（译者注：可参考 MDN 文档：属性的可枚举性和全部权）

---

掘金翻译计划 是一个翻译优质互联网技术文章的社区，文章来源为 掘金 上的英文分享文章。内容覆盖 Android、iOS、React、前端、后端、产品、设计 等领域，想要查看更多优质译文请持续关注 掘金翻译计划。