目录

简介

ESLint 的目标是提供一个插件化的 js 代码检测工具,保证代码风格的一致性和避免错误。

先决条件:

  • Node.js(>=4.x)
  • npm(>=2)

参考文章

关于代码规范/风格及ESLint

以下的安装/使用/配置ESLint的内容和方法其实都可以在eslint的官网或者中文网中找到,很详细;
至于其他的插件或者是第三方的扩展配置文件安装包则百度或者谷歌一下都可以解决;

最后强推airbnb在其官方github上有着4,9345个(截至写这篇文章时)star的Repository:Airbnb JavaScript Style Guide

安装及使用 ESLint

有两种方法安装 eslint:(1)全局安装;(2)局部安装

  1. 全局安装

    1
    $ yarn global add eslint

    使用:

    1
    2
    $ eslint --init
    $ eslint yourfile.js

    使用全局安装的 eslint 时,你使用的任何插件或可分享的配置也都必须在全局安装。

  2. 本地安装(推荐)

    1
    $ yarn add --dev eslint

    使用:

    1
    2
    $ ./node_modules/.bin/eslint --init
    $ ./node_modules/.bin/eslint yourfile.js

    使用本地安装的 eslint 时,你使用的任何插件或可分享的配置也都必须在本地安装。

入门简单使用:(以下实例均用全局安装的 eslint 作为例子)

1
2
3
# 入门常用命令,就两条
$ eslint --init # 在本目录下创建一份 eslint 的配置规则文件,一般为 eslintrc.js,详细能够用什么格式的文件,后续说明
$ eslint ./src/main.js # 使用创建的配置规则文件校验指定的js文件的语法和格式

简单配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
module.exports = {
"env": {
"browser": true, // 浏览器环境
"commonjs": true, // js文件的书写遵循commonjs格式
"es6": true // 遵循es6语法
},
"extends": [
"eslint:recommended", // 扩展使用eslint推荐的默认配置规则,也可以不使用,也可以阅读过详细的文档之后再决定
],
"parserOptions": {
"sourceType": "module" // 如果写的是ECMAScript模块,默认值是 "script"
},
"rules": { // 在此处自定义检查规则
"indent": [ // 缩进格式
"warn", // 检查不通过时的报错等级
"tab" // 指定缩进格式
],
"linebreak-style": [ // 换行时所采用的字符
"warn",
"unix"
],
"quotes": [ // 引用时使用单引号还是双引号
"warn",
"double"
],
"semi": [ // 是否需要分号
"warn",
"always"
],
"no-console": "off", // 可以使用console
"no-alert": "off", // 可以使用alert
"no-unused-vars": "warn" // 声明了但没有使用过的变量
}
};

配置 ESLint

书写 eslint 的规则配置信息有两种方式:

  1. 在 js 注释中书写规则配置信息
  2. 在 eslint 规则配置文件中书写规则

eslint 支持如下几种格式的配置文件:

  • JavaScript - 使用 .eslintrc.js 然后输出一个配置对象
  • YAML - 使用 .eslintrc.yaml.eslintrc.yml 去定义配置的结构
  • JSON - 使用 .eslintrc.json 去定义配置的结构,ESLint 的 JSON 文件允许 JavaScript 风格的注释
  • package.json - 在 根目录的package.json 里创建一个 eslintConfig属性,在那里定义你的配置
  • Deprecated - 使用 .eslintrc,可以使 JSON 也可以是 YAML

.eslintrc.yaml 格式的配置文件示例:

1
2
3
4
---
env:
browser: true
node: true

.eslintrc.json 格式的配置文件示例:

1
2
3
4
5
6
7
8
9
10
{
"name": "mypackage",
"version": "0.0.1",
"eslintConfig": {
"env": {
"browser": true,
"node": true
}
}
}

注意:可以在配置文件中书写规则配置信息,然后在 js 注释中再补充部分,两种方法配合使用。

ESLint 配置文件中常用的几个一级字段

1
2
3
4
5
6
7
8
9
10
11
// .eslintrc.js
module.exports = {
"root": true, // 或不写该属性,非必须属性
"env": {}, // 指定脚本的运行环境。每种环境都有一组特定的预定义全局变量
"parserOptions": {}, // 解析器选项
"parser": '', // 第三方解析器,ESLint 默认使用 Espree 作为解析器
"extends": [], // 或 字符串
"rules": [], // 启用的规则及其各自的错误级别
"plugins": [], // 规则插件
"globals": {}, // 脚本在执行期间访问的额外的全局变量
};
  • root - ESLint 一旦发现配置文件中有 “root”: true,它就会停止在父级目录中寻找。
  • env - 该属性设置与定义的全局变量,可用的环境有:(只列举出了常用的,完整的请查看官网)
    • browser - browser全局变量
    • node - Node.js 全局变量和 Node.js 作用域
    • commonjs - CommonJS 全局变量和 CommonJS 作用域 (仅为使用 Browserify/WebPack 写的只支持浏览器的代码)
    • shared-node-browser - Node 和 Browser 通用全局变量
    • es6 - 支持除模块外所有 ECMAScript 6 特性(该选项会自动设置 parserOptions.ecmaVersion 解析器选项为 6)
    • amd - 定义 require()define() 作为像 amd 一样的全局变量
  • parserOptions - 该属性设置解析器选项,常用的选项有:
    • ecmaVersion - 设置为 3, 5 (默认), 6(或写2015)、7(或写2016) 或 8(或写2017) 指定你想要使用的 ECMAScript 版本
    • sourceType - 设置为 “script” (默认) 或 “module”(如果你的代码是 ECMAScript 模块)
    • ecmaFeatures - 这是个对象,表示你想使用的额外的语言特性
      • globalReturn - 表示允许在全局作用域下使用 return
      • impliedStrict - 启用全局 strict mode(前提是 ecmaVersion 为 5 或更高)
      • jsx - 启用 JSX
  • extends - 一个配置文件可以被基础配置中的已启用的规则继承;属性值可取两种,且属性值可省略包名前缀 eslint-config-;ESLint 递归地进行扩展配置,所以一个基础的配置也可以有一个 extends 属性。

    • 在配置中指定的一个字符串
    • 字符串数组:每个配置继承她它前面的配置
      例如:
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      // .eslintrc.js
      module.exports = {
      extends: [
      // 启用一系列核心规则
      "eslint:recommended", // "eslint:all" //启用所有核心规则
      // 使用可共享配置包
      "standard," // extends 属性值可以省略包名的前缀 eslint-config-
      // 使用可共享的配置,单先要安装配置包,一般是npm包
      "airbnb", // or "airbnb/base"
      // 也可以是基本配置文件的绝对路径或相对路径
      "./node_modules/coding-standard/.eslintrc-jsx",
      // 也可以使用一些插件输出的配置文件,格式如下:
      /*
      ** plugin:<pkgname(ignore prefix like 'eslint-plugin-')>/<configuarionName>
      */
      "plugin:react/recommended",
      ],
      };

    可共享的配置是一个 npm 包,它输出一个配置对象;要确保这个上面提到的包都安装在 ESLint 能够请求到的目录下

  • parser - 可以指定第三方解析器
    ESLint 默认使用 Espree 作为其解析器,你可以在配置文件中指定一个不同的解析器,只要该解析器符合下列要求:

    • 它必须是本地安装的一个 npm 模块。
    • 它必须有兼容 Esprima 的接口(它必须输出一个 parse() 方法)
    • 它必须产出兼容 Esprima 的 AST 和 token 对象。

    另外,配置属性 parserOptions 仍然是必须的

  • rules - 在该属性中,你可以自行配置检查规则

    • “off” 或 0 - 关闭规则
    • “warn” 或 1 - 开启规则,使用警告级别的错误:warn (不会导致程序退出)
    • “error” 或 2 - 开启规则,使用错误级别的错误:error (当被触发的时候,程序会退出)
      例如:
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      // .eslintrc.js
      module.exports = {
      // ...
      "rules": { // 在此处自定义检查规则
      "quotes": [ // 引用时使用单引号还是双引号
      "warn",
      "double"
      ],
      "semi": [ // 是否需要分号
      "warn",
      "always"
      ],
      "no-console": "off", // 可以使用console
      "no-unused-vars": "warn" // 声明了但没有使用过的变量
      }
      // ...
      };
  • plugins - ESLint 支持使用第三方插件,但在使用之前,要用npm/yarn安装它们,插件名称可以省略eslint-plugin-前缀
    例如:

    1
    2
    # step1: 全局安装
    $ yarn global add eslint-plugin-react
    1
    2
    3
    4
    5
    6
    7
    8
    // step2: 进行配置 // .eslintrc.js
    module.exports = {
    //...
    plugins: [
    'react'
    ]
    //...
    };
  • globals - 当访问未定义的变量时,no-undef 规则将发出警告。如果你想在一个文件里使用全局变量,推荐你定义这些全局变量,这样 ESLint 就不会发出警告了。
    设置每个变量等于 true 允许变量被重写,或 false 不允许被重写。例如:

    1
    2
    3
    4
    5
    6
    {
    "globals": {
    "var1": true,
    "var2": false
    }
    }

ESLint 指定忽略不检查的文件或文件夹

eslint 指定忽略不检查的文件或文件夹的方法有两种:

  1. 可以通过在项目根目录创建一个 .eslintignore 文件告诉 ESLint 去忽略特定的文件和目录;
  2. 通过命令行指定带忽略配置的文件;

.eslintignore文件是一个纯文本文件,其中的每一行都是一个 glob 模式表明哪些路径应该忽略检测;
语法及使用方法基本和.gitignore文件保持相同:

  1. 以 # 开头的行被当作注释,不影响忽略模式
  2. 路径是相对于 .eslintignore 的位置或当前工作目录
  3. 忽略模式同 .gitignore 规范
  4. 以 ! 开头的行是否定模式,它将会重新包含一个之前被忽略的模式

也可以通过在 eslint 执行检查时的命令行指定其他名字的文本文件:

1
$ eslint --ignore-path .jshintignore myfile.js

关于 extendsplugins 的区别

extends 只是扩展规则配置。

plugins 是会参与到 ESLint 的检查流程里面去的,且创建的 ESLint 插件可以导出各种配置,包括规则配置。

加载借鉴 Airbnb 的配置文件

Airbnb JavaScript 规范说明的 github 仓库地址:
Airbnb JavaScript Style Guide
建议先参考阅读一下,再执行下一步安装配置文件包

Airbnb的配置文件安装包地址:
eslint-config-airbnb
其实只要按它上面的做就可以了,但是下面这是什么鬼,一开始根本不知道好吗!
图片

言归正传,按下面步骤走:

  1. 查看该安装包的依赖

    1
    $ yarn info eslint-config-airbnb peerDependencies

    图片

  2. 手动安装配置包和列表中的依赖

    1
    2
    # 若 eslint 安装在本地,则配置和依赖安装到本地或者是全局都是可以的
    $ yarn add --dev eslint-config-airbnb eslint-plugin-jsx-a11y eslint-plugin-import eslint-plugin-react

    1
    2
    # 若 eslint 安装在全局,则配置和依赖只能安装到全局才能被找到
    $ yarn global add eslint-config-airbnb eslint-plugin-jsx-a11y eslint-plugin-import eslint-plugin-react
  3. eslint 配置文件中引入共享配置文件

    1
    2
    3
    4
    5
    6
    7
    // .eslintrc.js
    module.exports = {
    extends: [
    "eslint:recommended",
    "airbnb", // or "airbnb/base"
    ]
    };

ESLint 集成到 Webpack 工程

ESLint 可以集成到其他工具中:

  • 编辑器
  • 构建工具
  • 测试工具
  • Git Hooks

参见:http://eslint.cn/docs/user-guide/integrations

要想集成到 Webpack,其实很简单,最核心的就是引入 eslint-loader

首先进行局部安装:

1
$ npm install -D eslint-loader

然后设置 webpack 配置文件的 module 字段,可以参考 vue 官方模板代码中的配置:

1
2
3
4
5
6
7
8
9
10
const createLintingRule = () => ({
test: /\.(js|vue)$/,
loader: 'eslint-loader',
enforce: 'pre',
include: [resolve('src'), resolve('test')],
options: {
formatter: require('eslint-friendly-formatter'),
emitWarning: !config.dev.showEslintErrorsInOverlay
}
})

接着在项目根目录下创建 .eslintrc.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// https://eslint.org/docs/user-guide/configuring

module.exports = {
root: true,
parserOptions: {
parser: 'babel-eslint'
},
env: {
browser: true,
},
extends: [
'plugin:vue/essential',
'standard'
],
// required to lint *.vue files
plugins: [
'vue'
],
// add your custom rules here
rules: {
// allow async-await
'generator-star-spacing': 'off',
// allow debugger during development
'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off'
}
}

注意到,配置文件中有一行:

1
parser: 'babel-eslint'

意思是声明使用 babel-eslint 作为引入的第三方解析器,因为我们会用 ES6 的语法和新的 API。

其次,在配置文件中的 extends 的字段,我们还使用了 standard,它其实就是 eslint-config-standard,只不过 extends 字段中的值可以省略 eslint-config-。我们在安装 eslint-config-standard 的时候,还必须手动安装如下 npm 包:

  • eslint-plugin-standard
  • eslint-plugin-promise
  • eslint-plugin-import
  • eslint-plugin-import

总的来说,直接这样安装:

1
$ npm install --save-dev eslint-config-standard eslint-plugin-standard eslint-plugin-promise eslint-plugin-import eslint-plugin-node

如果不想使用 eslint-config-standard 的同学,或许可以参考一下 standard 这个 npm 包:

eslint-config-standard 只是把 standard 做成兼容 ESLint 一起使用的 npm 包罢了。

这样就大功告成啦。