ESLint 是在 ECMAScript/JavaScript 代码中识别和报告模式匹配的工具，它的目标是保证代码的一致性和避免错误。ESLint 首先使用 AST 分析工具分析代码，然后使用插件配置生效的规则，针对预设的规则对代码进行检查，在不符合规则的时候提示&自动修复。你可以配置自己的代码检查规则，也可以根据已有的规则进行个性化的定制、扩展，甚至可以定制自己的规则。而在检查时，你也可以通过 js 注释在检查过程中灵活的开启、关闭和改变规则。

安装与使用

使用 npm 安装 ESLint：

1
$ npm install eslint --save-dev

初始化配置文件

1
$ npx eslint --init

运行 ESLint 进行代码检查

1
2
3
$ npx eslint yourfile.js
$ # 自动修复问题
$ npx eslint yourfile.js --fix

通常， ESLint 通过类似 .eslintrc.{js,yml,json} 的配置文件或者通过在 package.json 文件中添加 eslintConfig 键来对目录中的文件进行检查，这个文件可以通过执行 eslint --init 命令然后根据选择自动生成，生成后可以自由配置。

配置

以下介绍 .eslintrc.{js,yml,json} 配置文件中各字段含义：

env 环境

1
2
3
4
5
6
7
// .eslintrc.json
{
    "env": {
        "browser": true,
        "es2021": true
    }
}

指定脚本的运行环境。每种环境都有一组特定的预定义全局变量。可以指定多个运行环境。在执行 eslint 命令时可以通过添加 --env 指定检查的环境。在代码中可以通过添加 /* eslint-env node, mocha */ 指定特定的环境。

常用的环境包括:

env名 含义
browser 浏览器全局变量
node Nodejs全局变量和Nodejs范围
commonjs CommonJS全局变量和CommonJS范围（使用Browserify/webpack且仅运行在浏览器时使用）
es6 打开所有 ECMAScript 6 功能除了 modules（自动设置 parserOptions.ecmaVersion 为6）
es2021 添加所有 ECMAScript 2021 全局变量并自动将 parserOptions.ecmaVersion 设置为12

globals 全局变量

1
2
3
4
5
6
7
8
// .eslintrc.json
{
    "globals": {
        "app": "writable",
        "swan": "readonly",
        "Promise": "off"
    }
}

添加全局变量。 globals 下的 app swan 代表了为 ESLint 添加的全局变量。在代码中可以通过添加 /* global app:writable, swan:writable */ 指定添加全局环境变量。值 writeable 表示该全局变量可以被重写， readonly 表示不允许被重写, off 表示禁用该全局变量。

parser 解析器

指定 ESLint 使用的解析器。ESLint 默认使用 Espree 解析器。以下列出了ESLint支持的AST解析器

parser名 描述
Esprima jquery 团队提供的解析器，支持 ES9 ，符合 ESTree 标准语法树格式
Espree ESLint 默认解析器，基于 Esprima 发展而来并兼容 Esprima，支持 ES6
@babel/eslint-parser Babel 解析器的扩展，兼容 ESLint
@typescript-eslint/parser 支持 typescript 的 AST 解析器

parserOptions 解析器选项

1
2
3
4
5
6
7
8
9
10
// .eslintrc.json
{
    "parserOptions": {
        "ecmaVersion": 6,
        "sourceType": "module",
        "ecmaFeatures": {
            "jsx": true
        }
    }
}

通过 parserOptions 来选择支持特定的 JavaScript 版本和功能。ESLint 默认支持 ECMAScript5 语法。

以下是 parserOptions 的选项及其含义：

parserOptions选项 含义
ecmaVersion js 版本，默认5
sourceType js 类型，默认 “script”，”module” 表示是 ECMAScript 包
ecmaFeatures 表名额外支持的 js 功能，可取值 “globalReturn” 表示在全局范围允许 return ; “impliedStrict” 表示打开全局严格模式; “jsx” 表示支持 JSX

plugins 插件

1
2
3
4
5
6
7
// .eslintrc.json
{
    "plugins": [
        "plugin1",
        "eslint-plugin-plugin2"
    ]
}

添加插件。 ESLint 支持添加插件来进行额外的处理。 plugins 是数组结构，包括了插件的名字，插件需要通过 npm install 来安装，在 plugins 配置中可以省略插件的前缀 eslint-plugin- 。

processor 处理器

1
2
3
4
5
// .eslintrc.json
{
    "plugins": ["a-plugin"],
    "processor": "a-plugin/a-processor"
}

插件可以包含处理器。处理器可以将其他类型的文件转换成 Javascript 代码，然后可以使用 ESLint 进行一些预处理。

overrides 重写

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// .eslintrc.json
{
    "plugins": ["a-plugin"],
    "overrides": [
        {
            "files": ["*.md"],
            "processor": "a-plugin/markdown"
        },
        {
            "files": ["**/*.md/*.js"],
            "rules": {
                "strict": "off"
            }
        }
    ]
}

使用 overrides 可以对符合特定 glob 规则的文件进行特殊处理，包括执行特殊的规则或进行预处理。v4.1.0+版本支持。

rules 规则

1
2
3
4
5
6
7
8
// .eslintrc.json
{
    "rules": {
        "semi": ["error", "always"],
        "quotes": ["error", "double"],
        "plugin1/rule1": "error"
    }
}

指定脚本执行的规则。rules 下的 semi quotes 代表了 ESLint 规则， plugin1/rule1 代表了插件 plugin1 下的 rule1 规则。 第一个值代表了规则的错误等级，取值有以下三个

rules key取值 数值 含义
“off” 0 将规则关闭
“warn” 1 规则作为一个警告打开
“error” 2 规则作为一个错误打开（不符合规则将会退出）

第二个之后的值代表了规则的额外选项。
在代码中可以通过 /* eslint eqeqeq: "off", curly: 2, quotes: ["error", "double"] */ 修改规则。可以通过 /* eslint-disable eqeqeq, curly*/ 取消规则，通过 /* eslint-enable eqeqeq, curly*/ 打开某个规则。

可以通过以下写法对单行代码禁用 ESLint 规则（所有或单条、多条）： 

1
2
3
4
alert('foo'); // eslint-disable-line no-alert, plugin1/rule1 -- Here's a description about why this configuration is necessary.

// eslint-disable-next-line no-alert
alert('foo');

可以在ESLint代码规则后添加 -- 来对该条规则进行解释，例如： 

1
2
3
4
5
6
7
8
9
10
/* eslint eqeqeq: "off", curly: "error" -- Here's a description about why this configuration is necessary. */

/* eslint eqeqeq: "off", curly: "error"
    --------
    Here's a description about why this configuration is necessary. */

/* eslint eqeqeq: "off", curly: "error"
 * --------
 * This will not work due to the line above starting with a '*' character.
 */

ESLint Rules 记录了所有的 ESLint 规则，你也可以 自定义自己的规则。

extends 继承

1
2
3
4
// .eslintrc.json
{
    "extends": "eslint:recommended"
}

指定脚本执行的继承来源。 extends 表示你的规则继承自另一个配置，例如 eslint:recommended 代表所有 ESLint推荐规则（打✓的规则） 将会开启。
extends 可以配置成一个字符串来表示 配置文件的路径、可共享配置的名称、 eslint:recommended 或 eslint:all ，也可以配置成字符串数组来表示每个配置继承它前面的配置。

一些常用的继承配置包括：

extends名 包 介绍 特点
eslint:recommended - 启用 ESLint 推荐规则
eslint:all - 启用当前安装的 ESLint 中所有的核心规则(不推荐在产品中使用)
airbnb-base eslint-config-airbnb-base Airbnb推荐的代码风格 Airbnb号称是“最合理的编写 JavaScript 代码的方式”规范，规范写得比较全面，几乎覆盖了JavaScript的每一项特性
airbnb eslint-config-airbnb Airbnb推荐的代码风格，包括ES6和React
standard eslint-config-standard Standard代码风格 standard 号称是为了节省团队在代码风格上消耗的时间，规范十分简洁，0配置，提供了工具进行自动格式化，不支持修改。风格上使用两个空格缩进，使用单引号，不使用分号作为语句结束，不允许有多余的行末逗号
google eslint-config-google Google推荐的代码风格
react-app eslint-config-react-app Create React App 使用的代码风格

其他配置

配置名 值 含义
noInlineConfig true 禁用所有的内联配置注释，在命令中添加 --no-inline-config 可以起到同样的效果
reportUnusedDisableDirectives true 报告未使用的 eslint-disable 注释，在命令中添加 --report-unused-disable-directives 可以起到同样的作用
root true 表示该配置文件为项目根配置文件，无需向上检索（ESLint 对文件进行检查时会将离要检测的文件最近的配置文件作为最高优先级，然后检索父目录的配置）

检查优先级

ESLint 检查文件时的规则按照以下顺序执行

  1. 行内配置
    1. /*eslint-disable*/ 和 /*eslint-enable*/
    2. /*global*/
    3. /*eslint*/
    4. /*eslint-env*/
  2. 命令行选项（或 CLIEngine 等价物）：
    1. --global
    2. --rule
    3. --env
    4. -c、--config
  3. 项目级配置：
    1. 与要检测的文件在同一目录下的 .eslintrc.* 或 package.json 文件，优先级 .js > .yaml > .yml > .json > .eslintrc(弃用) > package.json
    2. 继续在父级目录寻找 .eslintrc 或 package.json 文件，直到根目录（包括根目录）或直到发现一个有 "root": true 的配置。
  4. 如果不是 1 到 3 中的任何一种情况，退回到 ~/.eslintrc 中自定义的默认配置。

忽略检查

可以通过在项目根目录创建一个 .eslintignore 文件告诉 ESLint 去忽略特定的文件和目录。.eslintignore 文件是一个纯文本文件，其中的每一行都是一个 glob 模式表明哪些路径应该忽略检测。 也可以在命令中添加参数 --ignore-pattern 来忽略指定文件、目录。除了 .eslintignore 文件中的模式，ESLint总是忽略 /node_modules/* 和 /bower_components/* 中的文件。除了使用 .eslintignore 文件，也可以在命令中添加参数 --ignore-path 来指定一个包含所有忽略文件的文本文件。如果没有发现 .eslintignore 文件，也没有指定替代文件，ESLint 将会在 package.json 中寻找 eslintIgnore 键，来检查要忽略的文件。

ESLint 命令

ESLint 除了可以安装到本地，也可以全局安装。ESLint 安装后可以直接执行 eslint -h 命令查看所有可选项

1
2
3
4
$ npm i -g eslint
$ eslint [options] [file|dir|glob]*
$ # 执行  eslint -h 命令可以查看有关 eslint 命令的帮助
$ eslint -h