[譯] ESLint v4.0.0 升級指南

時間 2019-11-17

標籤 eslint v4.0.0 升級指南简体版

原文原文鏈接

原文地址：ESLint Migrating to v4.0.0

原文做者：ESLint

譯文出自：掘金翻譯計劃

譯者：吃土小2叉

校對者：薛定諤的貓、sqrthree

ESLint v4.0.0 升級指南

ESLint v4.0.0 是 ESLint 的第 4 個主版本。固然，咱們但願大多數變動隻影響極少數用戶。本文旨在幫助您瞭解具體有哪些更改。前端

如下列表大體按每一個更改可能影響的用戶數量進行排序，排序越靠前影響的用戶數越多。react

ESLint 使用者請注意

ESLint 插件開發者和自定義規則開發者請注意

集成開發者請注意

`eslint:recommended` 新增規則

eslint:recommended 中新增了兩條規則：android

no-compare-neg-zero 不容許與 -0 進行比較
no-useless-escape 不容許在字符串和正則表達式中使用無心義的換行符

注: 若是要與 ESLint 3.x 的 eslint:recommended 保持一致，您能夠在配置文件中禁用上述規則：ios

{
  "extends": "eslint:recommended",

  "rules": {
    "no-compare-neg-zero": "off",
    "no-useless-escape": "off"
  }
}複製代碼

`indent` 規則將更嚴格

過去的 indent 規則在檢查縮進方面是至關寬容的：過去的縮進校驗規則會忽略許多代碼模式。而這會讓用戶產生困擾，由於他們偶爾會有不正確的代碼縮進，而且他們本指望 ESLint 可以發現這些問題（譯者補充：然而並無發現）。git

在 ESLint v4.0.0 中，indent 規則被重寫。新版規則將報告出舊版規則沒法發現的縮進錯誤。另外，MemberExpression 節點、函數聲明參數以及函數調用參數將默認進行縮進檢查（過去爲了向後兼容，這些默認都被忽略了）。github

爲了方便升級到 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 會拋出一個錯誤。api

注：升級後若是發現配置文件驗證出錯，請檢查配置文件中是否存在拼寫錯誤。若是使用了未識別的屬性，那麼應該將之從配置文件中移除，從而使 ESLint 恢復正常。less

忽略文件將從 .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 文檔：屬性的可枚舉性和全部權）