ESLint 使用指南

About

ESLint 是一款開源的 JavaScript lint 工具，由 Nicholas C. Zakas 於2013 年建立。

ESLint 官方文檔 About 頁面 分 About 和 Philosophy 兩個部分對 ESLint 作了介紹，簡潔明瞭，值得一讀。

藉助 ESLint，可將 靜態代碼分析 和 問題代碼協助修復 集成到 編碼、提交 和 打包 過程當中，及早發現並協助修復代碼中：

• 有語法錯誤的部分
• 不符合約定的樣式準則的部分
• 不符合約定的最佳實踐的部分

在項目開發中得到以下收益：

• 在執行代碼以前發現並修復語法錯誤，減小調試耗時和潛在 bug
• 保證項目的編碼風格統一，提升可維護性
• 督促團隊成員在編碼時遵照約定的最佳實踐，提升代碼質量

安裝

# Local Installation
yarn add -D eslint

# Global Installation
yarn add -g eslint
複製代碼

注意

• ESLint 藉助 nodejs 的模塊化機制引用插件。因此，全局安裝的 ESLint 只能使用全局安裝的 ESLint 插件，局部安裝的 ESLint 只能使用局部安裝的 ESLint 插件。

命令行接口

官方文檔：eslint.org/docs/user-g…

命令模式

# eslint [選項] [操做目標]
eslint [options] [file|dir|glob]*
複製代碼

注意

• 當使用 glob 語法指定操做目標時，glob 模式會被 shell 解析，解析結果可能因 shell 不一樣而不一樣。若是想要使用 node 的 glob 語法，必須使用引號將 glob 模式串引發來（在 Windows 中必須使用雙引號）。示例：

  eslint "lib/**"
  複製代碼

命令選項

使用 ESLint 命令時，能夠經過 eslint -h 概覽命令選項，找到本身須要的選項，而後後去官方文檔 命令行接口部分 查看該選項的詳細描述。

有些選項可接收一組參數，這類選項支持兩種傳參方式（有一個選項例外：--ignore-pattern 不支持第二種方式）：

1. 屢次指定同一選項，每次接收一個不一樣的參數
2. 將參數列表用逗號分隔，一次傳給選項

示例：

# 1.
eslint --ext .jsx --ext .js lib/

# 2.
eslint --ext .jsx,.js lib/
複製代碼

配置

相對路徑解析

配置文件中包含的相對路徑和 glob 模式都是基於當前配置文件的路徑進行解析的。

兩種主要的配置方式

1. 配置註釋 - 在目標文件中使用註釋語法嵌入配置信息。這種配置只對當前文件有效。
2. 配置文件 - 在 JavaScript、JSON 或 YAML 文件中定義配置信息。對於這種配置方式，配置信息能夠寫在單獨的 .eslintrc.* 文件中，或者寫在 package.json 文件的 eslintConfig 字段中。這種配置對配置文件所在目錄及其子目錄樹中的全部文件有效。

配置文件格式

• JavaScript - use .eslintrc.js 文件導出一個包含配置信息的對象。
• YAML - 使用 .eslintrc.yaml 或 .eslintrc.yml 定義配置。
• JSON - 使用 .eslintrc.json 定義配置信息，JSON 文件中支持 JavaScript 註釋。
• package.json - 在 package.json 文件中增長一個 eslintConfig 字段，在該字段中定義配置信息。
• .eslintrc - 已廢棄

若是在同一個目錄中有多個配置文件，則它們中間只有一個是有效的，優先級以下：

1. .eslintrc.js
2. .eslintrc.yaml
3. .eslintrc.yml
4. .eslintrc.json
5. .eslintrc
6. package.json

配置層疊

官方文檔：eslint.org/docs/user-g…

項目級配置文件

在同一個項目中，能夠爲不一樣目錄指定不一樣的配置文件。

當 lint 一個文件時，ESLint ：

1. 從文件所在目錄開始，在目錄樹中依次向上搜索配置文件，直到系統根目錄，或者直到找到一個包含 root: true 配置參數的配置文件，最終獲得一個配置文件列表。
2. 合併上一步獲得的配置文件列表中的配置項，獲得最終的配置文件配置。合併配置項時，在目錄樹中距離 lint 目標越近的配置文件具備越高的優先級。
3. 執行其他步驟。

完整的配置層疊關係

ESLint 配置除了經過配置文件指定，還能夠經過註釋內嵌或命令行選項指定。Lint 一個文件所使用的最終配置是各類配置合併的結果，合併時各類配置的優先級以下：

1. 註釋內嵌配置

   1. /*eslint-disable*/ and /*eslint-enable*/
   2. /*global*/
   3. /*eslint*/
   4. /*eslint-env*/

2. 經過命令行選項指定的配置

   1. --global
   2. --rule
   3. --env
   4. -c, --config

3. 項目級配置文件

4. 若是沒有找到項目級配置文件，而且沒有或沒有找到經過 --config 指定配置文件，則去用戶家目錄（~/）下搜索配置文件。

若是上述配置均不存在，則 ESLint 拋出 noConfigError。

配置參數

• parser

  指定 ESLint 使用的語法分析器。ESLint 兼容的語法分析器有：Esprima、Babel-ESLint、@typescript-eslint/parser，ESLint 默認使用 Esprima。

• parserOptions

  指定語法分析器選項，默認使用的語法分析器支持以下幾個選項：ecmaVersion、sourceType、ecmaFeatures。示例：

  {
    "parserOptions": {
      "ecmaVersion": 6,
      "sourceType": "module",
      "ecmaFeatures": {
        "jsx": true
      }
    }
  }
  複製代碼

  不一樣的語法分析器可能具備不一樣的選項。

• env

  指定執行環境，一個執行環境會預約義一組全局變量。示例：

  使用註釋配置

  /* eslint-env node, mocha */
  複製代碼

  使用配置文件：

  {
    "env": {
      "browser": true,
      "node": true
    }
  }
  複製代碼

• globals

  使用未在當前文件中定義的全局變量時，會命中 no-undef 規則，經過 globals 配置指定的全局變量無視 no-undef 規則。示例：

  使用註釋配置

  /* global var1, var2 */
  
  /* global var1:writable, var2:writable */
  複製代碼

  在配置文件中指定：

  {
    "globals": {
      "var1": "writable",
      "var2": "readonly"
    }
  }
  複製代碼

• plugins

  插件是第三方定製的規則集合，plugins 參數用於指定第三方插件，插件名中的 eslint-plugin- 前綴能夠省略。示例：

  {
    "plugins": [
      "plugin1",
      "eslint-plugin-plugin2"
    ]
  }
  複製代碼

  使用插件時必須安裝其 npm 包。

  注意

  • 受限於 Node 的模塊化機制，全局安裝的 ESLint 只能使用全局安裝的插件，局部安裝的 ESLint 只能使用局部安裝的插件，不支持全局插件和局部插件的混合使用。

• rules

  指定 ESLint 校驗規則。

  全部規則獨立於其餘規則，可單獨配置。

  ESLint 內置規則：eslint.org/docs/rules/

  規則組成：規則名、錯誤級別、附加選項

  規則配置模式：

  規則名: [錯誤級別, 附加選項]
  
  規則名: 錯誤級別
  複製代碼

  示例：

  "rules": {
    "semi": ["error", "always"],
    "quotes": ["error", "double"]
  }
  複製代碼

  在上述示例中，"semi" 和 "quotes" 是規則名，"error" 是規則錯誤級別，"always" 和 "quotes" 分別是 semi 和 quotes 各自特有的附加選項。

  ESLint 定義了三種錯誤級別：

  • "off" 或 0 - 關閉，不校驗該規則
  • "warn" 或 1 - 警告，不影響 exit code
  • "error" 或 2 - 錯誤，觸發該規則時 exit code 爲 1 關於規則的錯誤級別，在 ESLint 特性概覽 部分已有介紹。

  使用註釋配置

  /* eslint eqeqeq: "off", curly: "error" */
  
  // 若是規則有額外選項，能夠用數組字面量語法
  /* eslint quotes: ["error", "double"], curly: 2 */
  複製代碼

  使用配置文件

  {
    "rules": {
      "eqeqeq": "off",
      "curly": "error",
      "quotes": ["error", "double"]
    }
  }
  複製代碼

  可在文件中使用註釋配置禁用所有規則或指定規則：

  • 塊級禁用

    /* eslint-disable */
    alert('foo');
    /* eslint-enable */
    
    /* eslint-disable no-alert, no-console */
    alert('foo');
    console.log('bar');
    /* eslint-enable no-alert, no-console */
    複製代碼

  • 文件級禁用

    /* eslint-disable */
    alert('foo');
    
    /* eslint-disable no-alert */
    alert('foo');
    複製代碼

  • 在指定行中禁用

    alert('foo'); // eslint-disable-line
    alert('foo'); // eslint-disable-line no-alert
    alert('foo'); // eslint-disable-line no-alert, quotes, semi
    alert('foo'); /* eslint-disable-line */
    alert('foo'); /* eslint-disable-line no-alert */
    alert('foo'); /* eslint-disable-line no-alert, quotes, semi */
    
    // eslint-disable-next-line
    // eslint-disable-next-line no-alert
    // eslint-disable-next-line no-alert, quotes, semi
    /* eslint-disable-next-line */
    /* eslint-disable-next-line no-alert */
    /* eslint-disable-next-line no-alert, quotes, semi */
    alert('foo');
    複製代碼

• overrides

  示例：

  {
    "rules": {...},
    "overrides": [
      {
        "files": ["*-test.js","*.spec.js"],
        "excludedFiles": "*.test.js",
        "rules": {
          "no-unused-expressions": "off"
        }
      }
    ]
  }
  複製代碼

  對於匹配 overrides.files 且不匹配 overrides.excludedFiles 的 文件，overrides.rules 中的規則會覆蓋 rules 中的同名規則。

• settings

  指定一個對象，這個對象會被提供給每個將要執行的規則。

• root

  ESLint 在目錄樹種搜索配置文件時，若遇到 root 參數爲 true 的配置文件，就會中止搜索，不然沿着目錄樹一直向父級目錄的方向搜索到系統根目錄爲止。

• extends

  配置文件能夠在已有配置的基礎上進行擴展，extends 用於指定基礎配置。該參數的值爲如下之一：

  • 一個指定基礎配置來源的字符串
  • 一個指定基礎配置來源的字符串的數組：數組中每一個配置擴展它前面的配置

  ESLint 支持遞歸擴展配置，因此基礎配置中也可包含 extends 參數。

  當指定基礎配置時，rules 參數指定的規則可按以下幾種方式進行擴展：

  • 啓用基礎配置中沒有規則
  • 繼承基礎配置中的規則，改變其錯誤級別，但不改變其附加選項：
    • 基礎配置: "eqeqeq": ["error", "allow-null"]
    • 擴展配置: "eqeqeq": "warn"
    • 最終有效配置："eqeqeq": ["warn", "allow-null"]
  • 覆蓋基礎配置中的規則:
    • 基礎配置："quotes": ["error", "single", "avoid-escape"]
    • 擴展配置："quotes": ["error", "single"]
    • 最終有效配置: "quotes": ["error", "single"]

  使用 extends 指定的基礎配置來源能夠是：

  • eslint:recommended，啓用 ESLint 內置規則集 的一個子集。

  • 共享配置包，一類導出 ESLint 配置對象的 npm 包，好比 eslint-config-standard、eslint-config-airbnb 等。共享配置包須要安裝才能使用，配置時可省略報名中的 eslint-config- 前綴。

    示例：

    {
      "extends": ["airbnb"]
      "rules": {
        "no-set-state": "off"
      }
    }
    複製代碼

  • 插件導出的命名配置，其配置值由如下幾部分組成：

    • plugin:
    • 插件包名（可省略前綴，例如：react）
    • /
    • 配置名（例如：recommended）

    示例：

    {
      "plugins": [
        "react"
      ],
      "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
      ],
      "rules": {
        "no-set-state": "off"
      }
    }
    複製代碼

  • 配置文件，經過配置文件的絕對路徑或相對路徑指定。

    示例：

    {
      "extends": [
        "./node_modules/coding-standard/eslintDefaults.js",
        "./node_modules/coding-standard/.eslintrc-es6",
        "./node_modules/coding-standard/.eslintrc-jsx",
        "./my-eslint-config.js"
      ],
      "rules": {
        "eqeqeq": "warn"
      }
    }
    複製代碼

  • eslint:all，啓動全部 ESLint 內置規則，不推薦。

• 忽略文件和目錄

  使用 .eslintignore 文件指定要忽略的文件和目錄，忽略模式的指定使用 .gitignore 的 規範。

  ESLint 默認忽略 /node_modules/* 和 /bower_components/*。

  示例：

  # /node_modules/* and /bower_components/* in the project root are ignored by default
  
  # Ignore built files except build/index.js
  build/*
  !build/index.js
  複製代碼

基於 eslint-config-airbnb 擴展配置

eslint-config-airbnb 是一個 ESLint 共享配置包，支持 ECMAScript 6+ 和 React。

安裝 eslint-config-airbnb

# 安裝 eslint-config-airbnb
yarn add -D eslint-config-airbnb@latest

# 獲取 peerDependencies
npm info "eslint-config-airbnb@latest" peerDependencies

# 安裝 peerDependencies
yarn add -D <dependency_1>@<version> <dependency_2>@<version> ...
複製代碼

eslint-config-airbnb 依賴的插件

• eslint-plugin-import - 支持 ES6+ import / export 語法以及模塊路徑有效性的校驗。
• eslint-plugin-react - 支持 React 編碼規範的校驗。
• eslint-plugin-jsx-a11y - 支持 HTML 元素可訪問性的校驗。

配置示例

// .eslintrc.js

module.exports = {
    root: true,
    extends: ['airbnb'],
    parserOptions: {
        // eslint-config-airbnb: { ecmaVersion: 6, sourceType: 'module' }
        ecmaFeatures: {
            // eslint-config-airbnb: { jsx: true, es6: true }
            generators: true,
        },
    },
    env: {
        // eslint-config-airbnb: { node: true, es6: true }
        browser: true,
    },
    rules: {
        indent: ['error', 4],
    },
}
複製代碼

使用 eslint-import-resolver-webpack

若是開啓了 eslint-plugin-import no-unresolved 規則，能夠藉助該插件使用 webpack 的 resolve 配置解析模塊路徑。

安裝

yarn add -D eslint-import-resolver-webpack
複製代碼

配置方式：

{
    "settings": {
        "import/resolver": "webpack", // 使用 webpack 默認配置
    }
}
複製代碼

{
    "settings": {
        "import/resolver": {
            "webpack": {
                "config": "webpack.dev.config.js" // 指定要使用的 webpack 配置文件
            }
        }
    }
}
複製代碼

{
    "settings": {
        "import/resolver": {
            "webpack": {
                "config": { // 定義 webpack 配置對象
                    "resolve": {
                        "extensions": [".js", ".jsx"]
                    }
                }
            }
        }
    }
}
複製代碼

使用 babel-eslint

babel-eslint 是一款用於 ESLint 的語法分析器，它支持使用 ESLint 分析全部 babel 兼容的代碼。

使用 babel-eslint 須要安裝 babel 並提供 babel 配置文件。

ESLint 核心規則不支持實驗階段的語法，若是要使用這部分語法，須要配合 eslint-plugin-babel 使用。

安裝

# 安裝 babel-eslint
yarn add -D babel-eslint

# 安裝 eslint-plugin-babel
yarn add -D eslint-plugin-babel
複製代碼

配置

{
    "parser": "babel-eslint",
    "plugins": ["babel"]
}
複製代碼

集成

VSCode 集成

代碼提示

工具：VSCode ESLint 插件

使用：在 VSCode 設置中將 eslint.enable 設置爲 true

代碼修復

工具：VSCode Prettier 插件

使用：在 VSCode 設置中將 prettier.eslintIntegration 設置爲 true，prettier 插件執行格式化時將使用 prettier-eslint 完成下述操做：

1. 使用 prettier 格式化代碼
2. 對上一步格式化過的代碼執行 eslint --fix

相比於直接使用 eslint --fix 命令，prettier 插件：

• 支持快捷鍵
• 支持更多的代碼格式化選項
• 支持其餘類型文件的格式化

git commit 集成

在提交代碼時，lint git 暫存區的代碼，若 lint 不經過則中斷提交，保證問題代碼不進入代碼倉庫。

工具：

• husky - 提供 git hooks 支持
• lint-staged - 對暫存文件（staged files）中匹配指定 glob 模式的文件執行指定的 shell 命令。

配置示例：

package.json

{
    "husky": {
        "hooks": {
            "pre-commit": "lint-staged"
        }
    },
    "lint-staged": {
        "linters": {
            "**/*.js": ["eslint --fix", "git add"]
        },
        "ignore": ["**/{dist,build}/**/*.js", "**/*.min.js"]
    }
}
複製代碼

其餘集成

eslint.org/docs/user-g…

完整配置示例

module.exports = {
    root: true,
    extends: ['airbnb'],
    plugins: ['babel'],
    parser: 'babel-eslint',
    parserOptions: {
        ecmaFeatures: {
            generators: true,
        },
    },
    env: {
        browser: true,
    },
    rules: {
        indent: ['error', 4],
    },
    settings: {
        'import/resolver': {
            // 識別 webpack 配置的路徑別名
            webpack: {
                config: 'webpack.config.js',
            }
        },
    },
}

/** peerDependencies: { "babel-eslint": "^10.0.1", "eslint": "^5.15.0", "eslint-config-airbnb": "^17.1.0", "eslint-import-resolver-webpack": "^0.11.0", "eslint-plugin-babel": "^5.3.0", "eslint-plugin-import": "^2.14.0", "eslint-plugin-jsx-a11y": "^6.1.1", "eslint-plugin-react": "^7.11.0", } */
複製代碼