遷移至 v4.0.0

ESLint v4.0.0 是第四個主要版本發布。我們在此版本中進行了幾項重大變更；但是，我們預期大多數變更只會影響非常小比例的使用者。本指南旨在引導您了解這些變更。

以下列表大致按照每個變更預期影響的使用者數量排序，其中第一個項目預期影響的使用者最多。

使用者的重大變更

已將新規則新增至 eslint:recommended
indent 規則更嚴格
設定檔中無法辨識的屬性現在會導致嚴重錯誤
.eslintignore 模式現在從檔案的位置解析
padded-blocks 規則預設更嚴格
space-before-function-paren 規則預設更嚴格
no-multi-spaces 規則預設更嚴格
設定檔中對具範圍外掛程式的參考現在必須包含範圍

外掛程式/自訂規則開發者的重大變更

RuleTester 現在驗證測試案例的屬性
AST 節點不再具有 comment 屬性
LineComment 和 BlockComment 事件將不再於 AST 遍歷期間發出
Shebangs 現在從 comment API 傳回

`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 規則現在將強制執行非同步箭頭函數的間距。先前，除非使用者選擇強制執行，否則規則會忽略這些情況。

解決方法： 若要模擬 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() (傳回檔案中的所有註解)，並允許透過各種其他語彙單元迭代器方法 (例如具有 { includeComments: true } 選項的 getTokenBefore() 和 getTokenAfter()) 存取註解。

對於關心支援 ESLint v3.0 以及 v4.0 的規則作者，現在已棄用的 sourceCode.getComments() 仍然可用，並且適用於這兩個版本。

最後，請注意，以下 SourceCode 方法已被棄用，將在未來版本的 ESLint 中移除

getComments() - 已由 getCommentsBefore()、getCommentsAfter() 和 getCommentsInside() 取代
getTokenOrCommentBefore() - 已由具有 { includeComments: true } 選項的 getTokenBefore() 取代
getTokenOrCommentAfter() - 已由具有 { includeComments: true } 選項的 getTokenAfter() 取代

在 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

Shebangs 現在從 comment 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 規則預設更嚴格