Eslint使用入门指南

官方文档【英文版】 英文文档

官方文档【中文版】 中文文档

原文地址【原地址】 博客地址

Eslint是用来干嘛的

ESLint最初是由Nicholas C. Zakas 于2013年6月创建的开源项目。它的目标是提供一个插件化的javascript代码检测工具。

为什么要使用Eslint

ESLint 是一个开源的 JavaScript 代码检查工具,。代码检查是一种静态的分析，常用于寻找有问题的模式或者代码，并且不依赖于具体的编码风格。对大多数编程语言来说都会有代码检查，一般来说编译程序会内置检查工具。

但是由于javascript的动态弱类型语言特性，导致在开发中如果不加以约束会容易出错，也正是因为这种特性导致当程序出现错误的时候，我们需要花费更多的时间在执行的过程中不断去调试，Eslint的出现就是为了让开发人员可以在开发的过程中就发现错误而非在执行过程中。

Eslint保持其插件的特性，让开发人员自定义定制属于自己的规则，也可以去遵循一些大的社区或者团队的规范直接继承下来用于使用，其所有规则都是可插入的，同时为了方便使用，也对其内置了一些规则。

安装

• 局部安装：npm install eslint --save-dev
• 全局安装：npm install eslint -g
• 版本要求 nodejs >= 6.14、 npm 3+

使用

首先我们要使用eslint我们需要配置一份eslint的专属配置文件放置在项目的根目录上，可以用个cli命令行工具直接生成，如果是全局安装可以直接eslint --int、如果是本地安装则./node_modules/.bin/eslint --init两个操作没有区别接下来会生成一份基础的Eslint配置文件，你可以选择JS、JSON、YAML等格式、同时在其中可以选择一些你需要的规则，如果你是初次上次，那么我建议你全部回车，在选择框架的地方建议首次选择none，暂时我们先不去考虑如何集成框架，接下来就可以生成下图的一份配置，全部标上注释更方便你的理解。

module.exports = {
    "env": { // 环境
        "browser": true,
        "es2021": true
    },
    "extends": "eslint:recommended", // 可共享配置的名称、eslint:recommended 或 eslint:all,表示默认开启一些内置的规则，包含的，在 https://eslint.bootcss.com/docs/rules/ 中可以查看内置规则
    "parserOptions": {
        "ecmaVersion": "latest", // 指定你想要使用的 ECMAScript 版本
        "sourceType": "module" //"script" (默认) 或 "module"（如果你的代码是 ECMAScript 模块)
    },
    "rules": { // 配置规则的地方 这里就是我们所需要配置的规则
    }
}
​

规则配置

基础配置规则注意事项

• "off" 或 0 - 关闭规则

• "warn" 或 1 - 开启规则，使用警告级别的错误：warn (不会导致程序退出)

• "error" 或 2 - 开启规则，使用错误级别的错误：error (当被触发的时候，程序会退出)

• 正常的配置通常是键值对的形式，那么这一类的配置是没有属性的只需要开启关闭即可类似于

  "no-cond-assign": 2,
  "no-console": 1,
  

  当然部分属性有自己的属性，在控制开关的同时还需要配置属性，例如

  {
      rules: {
          'quotes': ['error', 'single'],  // 如果不是单引号，则报错
          'one-var': ['error', {
              'var': 'always',  // 每个函数作用域中，只允许 1 个 var 声明
              'let': 'never',   // 每个块作用域中，允许多个 let 声明
              'const': 'never', // 每个块作用域中，允许多个 const 声明
          }]
      }
  }
  

• Eslint的配置格式可以包含以下五种

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

• 当出现多份配置的时候则会按以下优先级进行排列

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

常用配置规则列表【更多规则参官方文档】

配置属性		配置说明	推荐配置
comma-dangle		是否允许对象中出现结尾逗号	["error", "never"]
no-cond-assign		条件语句的条件中不允许出现赋值运算符	2
no-console		不允许出现console语句	2
no-constant-condition		条件语句的条件中不允许出现恒定不变的量	2
no-control-regex		正则表达式中不允许出现控制字符	2
no-debugger		不允许出现debugger语句	2
no-dupe-args		函数定义的时候不允许出现重复的参数	2
no-dupe-keys		对象中不允许出现重复的键	2
no-duplicate-case		switch语句中不允许出现重复的case标签	2
no-empty		不允许出现空的代码块	2
no-empty-character-class		正则表达式中不允许出现空的字符组	2
no-ex-assign		在try catch语句中不允许重新分配异常变量	2
no-extra-boolean-cast		不允许出现不必要的布尔值转换	2
no-extra-parens		不允许出现不必要的圆括号	0
no-extra-semi		不允许出现不必要的分号	2
no-func-assign		不允许重新分配函数声明	2
no-inner-declarations		不允许在嵌套代码块里声明函数	["error", "functions"]
no-invalid-regexp		不允许在RegExp构造函数里出现无效的正则表达式	2
no-irregular-whitespace		不允许出现不规则的空格	2
no-negated-in-lhs		不允许在in表达式语句中对最左边的运算数使用取反操作	2
no-obj-calls		不允许把全局对象属性当做函数来调用	2
no-regex-spaces		正则表达式中不允许出现多个连续空格	2
quote-props		对象中的属性名是否需要用引号引起来	2
no-sparse-arrays		数组中不允许出现空位置	2
no-unreachable		在return，throw，continue，break语句后不允许出现不可能到达的语句	2
use-isnan		要求检查NaN的时候使用isNaN()	2
valid-jsdoc		强制JSDoc注释	["error", {"requireReturn": false, "requireParamDescription": false, "requireReturnDescription": true }]
valid-typeof		在使用typeof表达式比较的时候强制使用有效的字符串	["error", { "requireStringLiterals": true }]
block-scoped-var		将变量声明放在合适的代码块里	2
complexity		限制条件语句的复杂度	0
consistent-return		无论有没有返回值都强制要求return语句返回一个值	2
curly		强制使用花括号的风格	["error", "all"]
default-case		在switch语句中需要有default语句	0
dot-notation		获取对象属性的时候使用点号	["error", {"allowKeywords": false, "allowPattern": ""}]
eqeqeq		比较的时候使用严格等于	["error", "smart"]
no-alert		不允许使用alert，confirm，prompt语句	1
no-caller		不允许使用arguments.callee和arguments.caller属性	2
guard-for-in		监视for in循环，防止出现不可预料的情况	0
no-div-regex		不能使用看起来像除法的正则表达式	2
no-else-return		如果if语句有return，else里的return不用放在else里	0
no-labels		不允许标签语句	["error", { "allowLoop": false "allowSwitch": false }]
no-eq-null		不允许对null用==或者!=	2
no-eval		不允许使用eval()	2
no-extend-native		不允许扩展原生对象	2
no-extra-bind		不允许不必要的函数绑定	2
no-fallthrough		不允许switch按顺序全部执行所有case	2
no-floating-decimal		不允许浮点数缺失数字	2
no-implied-eval		不允许使用隐式eval()	2
no-iterator		不允许使用__iterator__属性	2
no-lone-blocks		不允许不必要的嵌套代码块	2
no-loop-func		不允许在循环语句中进行函数声明	2
no-multi-spaces		不允许出现多余的空格	2
no-multi-str		不允许用\来让字符串换行	2
no-global-assign		不允许重新分配原生对象	2
no-new		不允许new一个实例后不赋值或者不比较	2
no-new-func		不允许使用new Function	2
no-new-wrappers		不允许使用new String，Number和Boolean对象	2
no-octal		不允许使用八进制字面值	2
no-octal-escape		不允许使用八进制转义序列	2
no-param-reassign		不允许重新分配函数参数	0
no-redeclare		不允许变量重复声明	2
no-return-assign		不允许在return语句中使用分配语句	2
no-script-url		不允许使用javascript:void(0)	2
no-self-compare		不允许自己和自己比较	2
no-sequences		不允许使用逗号表达式	2
no-throw-literal		不允许抛出字面量错误 throw "error"	2
no-unused-expressions		不允许无用的表达式	2
no-void		不允许void操作符	2
no-warning-comments		不允许警告备注	[1, {"terms": ["todo", "fixme", "any other term"]}]
no-with		不允许使用with语句	2
radix		使用parseInt时强制使用基数来指定是十进制还是其他进制	1
vars-on-top		var必须放在作用域顶部	0
wrap-iife		立即执行表达式的括号风格	[2, "any"]
yoda		不允许在if条件中使用yoda条件	[2, "never", {"exceptRange": true}]
strict		使用严格模式	[2, "function"]
no-catch-shadow		不允许try catch语句接受的err变量与外部变量重名	2
no-label-var		不允许标签和变量同名	2
no-shadow		外部作用域中的变量不能与它所包含的作用域中的变量或参数同名	2
no-shadow-restricted-names		js关键字和保留字不能作为函数名或者变量名	2
no-undef		不允许未声明的变量	2
no-undef-init		不允许初始化变量时给变量赋值undefined	2
no-undefined		不允许把undefined当做标识符使用	2
no-unused-vars		不允许有声明后未使用的变量或者参数	[2, {"vars": "all", "args": "after-used"}]
no-use-before-define		不允许在未定义之前就使用变量	[2, "nofunc"]
brace-style		大括号风格	[2, "1tbs", { "allowSingleLine": false}]
camelcase		强制驼峰命名规则	[2, {"properties": "never"}]
comma-style		逗号风格	[2, "last"]
consistent-this		当获取当前环境的this是用一样的风格	[0, "self"]
eol-last		文件以换行符结束	2
func-names		函数表达式必须有名字	0
func-style		函数风格，规定只能使用函数声明或者函数表达式	0
key-spacing		对象字面量中冒号的前后空格	[2, {"beforeColon": false, "afterColon": true}]
max-nested-callbacks		回调嵌套深度	0
new-cap		构造函数名字首字母要大写	[2, {"newIsCap": true, "capIsNew": false}]
new-parens		new时构造函数必须有小括号	2
newline-after-var		变量声明后必须空一行	0
no-array-constructor		不允许使用数组构造器	2
no-inline-comments		不允许行内注释	0
no-lonely-if		不允许else语句内只有if语句	0
no-mixed-spaces-and-tabs		不允许混用tab和空格	[2, "smart-tabs"]
no-multiple-empty-lines		空行最多不能超过两行	[2, {"max": 2}]
no-nested-ternary		不允许使用嵌套的三目运算符	2
no-new-object		禁止使用new Object()	2
fun-call-spacing		函数调用时，函数名与()之间不能有空格	2
no-ternary		不允许使用三目运算符	0
no-trailing-spaces		一行最后不允许有空格	2
no-underscore-dangle		不允许标识符以下划线开头	2
no-extra-parens		不允许出现多余的括号	0
one-var		强制变量声明放在一起	0
operator-assignment		赋值运算符的风格	0
padded-blocks		块内行首行尾是否空行	[2, "never"]
quote-props		对象字面量中属性名加引号	0
quotes		引号风格	[1, "single", "avoid-escape"]
semi		强制语句分号结尾	[2, "always"]
semi-spacing		分后前后空格	[2, {"before": false, "after": true}]
sort-vars		变量声明时排序	0
space-before-blocks		块前的空格	[2, "always"]
space-before-function-paren		函数定义时括号前的空格	[2, {"anonymous": "always", "named": "never"}]
space-infix-ops		操作符周围的空格	[2, {"int32Hint": true}]
keyword-spacing		关键字前后的空格	2
space-unary-ops		一元运算符前后不要加空格	[2, { "words": true, "nonwords": false}]
wrap-regex		正则表达式字面量用括号括起来	2
no-var		使用let和const代替var	0
generator-star-spacing		生成器函数前后空格	[2, "both"]
max-depth		嵌套块深度	0
max-len		一行最大长度，单位为字符	0
max-params		函数最多能有多少个参数	0
max-statements		函数内最多有几个声明	0
no-bitwise		不允许使用位运算符	0
no-plusplus		不允许使用++ --运算符	0
indent		强制一致的缩进风格	2
no-delete-var		不允许使用delete操作符	2
no-proto		不允许使用__proto__属性	2

ESLint 提供了大量内置的规则，这里是它的规则列表 ESLint Rules，除此之外你还可以通过插件来添加更多的规则。

推荐团队规范开源配置

上述是一些基础的配置，具体的使用呢可以自己去配置，一般这类规则的配置可以参照市面上比较流行的规范，使用别人的规范加自己的配置进行结合。市面上目前最为流行的开源配置使用最多的是airbnb团队的配置。下面这些配置值得推荐：

• eslint:recommended ESLint内置的推荐规则在么有讲到 所有打钩的就是内置规则
• eslint:all：ESLint 内置的所有规则；
• eslint-config-standard：standard 的 JS 规范；
• eslint-config-prettier：关闭和 ESLint 中以及其他扩展中有冲突的规则；
• eslint-config-airbnb-base：airbab 的 JS 规范；
• eslint-config-alloy：腾讯 AlloyTeam 前端团队出品，可以很好的针对你项目的技术栈进行配置选择，比如可以选 React、Vue（现已支持 Vue 3.0）、TypeScript 等；

如何使用

想要使用别人的配置通常只需要下载对应的依赖并且加入到extends继承下来即可，可以配置为字符串或者数组均可。

{
    extends: [
        'eslint:recommended', // 是 ESLint 官方的扩展,内置推荐规则
        'plugin:vue/essential', // 是插件类型扩展
        'eslint-config-standard', // eslint-config 开头的都可以省略掉前面 直接使用standard即可
        '@vue/prettier', // @开头扩展和 eslint-config 一样，只是在 npm 包上面加了一层作用域 scope；
        './node_modules/coding-standard/.eslintrc-es6' // 一个执行配置文件的路径
    ]
}
​

如何使用插件 plugins

ESlint的插件是干嘛的：

首先我们需要知道的Eslint本质只是一个代码检测工具，默认情况下也只能检测js文件，如果我们需要在工程化中加入去兼容其他语法例如[.vue]、[.jsx]等其他格式的文件时就没有办法实现，所以我们需要加入一些插件来实现对非js格式的文件进行检测。

# 如何配置plugin

ESlint相关的插件有两种命令名形式，带命名空间的和带的，比如

• eslint-plugin-xxx 以eslint-plugin-开头的都可以直接省略掉 类似上面的extends继承规则只需要 xxx就行
• @开头表示带命名空间的就正常引入即可

{   
  plugins: [        
    'jquery',// 是指 eslint-plugin-jquery        
    '@jquery/jquery',  // 是指 @jquery/eslint-plugin-jquery        
    '@foobar', // 是指 @foobar/eslint-plugin    ] 
}

当需要基于插件进行 extends 和 rules 的配置的时候，需要加上插件的引用，比如：

{
    plugins: [
        'jquery',   // eslint-plugin-jquery
        '@foo/foo', // @foo/eslint-plugin-foo
        '@bar,      // @bar/eslint-plugin
    ],
    extends: [
        'plugin:jquery/recommended',
        'plugin:@foo/foo/recommended',
        'plugin:@bar/recommended'
    ],
    rules: {
        'jquery/a-rule': 'error',
        '@foo/foo/some-rule': 'error',
        '@bar/another-rule': 'error'
    },
}

以上配置来自 ESLint plugins

热门开源规范推荐

如何知道某个扩展有哪些规则可以配置，以及每个规则具体限制？ 这里直接给出业内著名且使用比较多的规则列表的快速链接：

• ESLint rules，这整个列表对应 eslint:all，而打钩 ✔️ 的是 eslint:recommenmed；
• Prettier rules
• standard rules
• airbnb rules
• AlloyTeam vue rules

规则的优先级

• 如果 extends 配置的是一个数组，那么最终会将所有规则项进行合并，出现冲突的时候，后面的会覆盖前面的；
• 通过 rules 单独配置的规则优先级比 extends 高；

其他配置

配置当前目录为 root

ESLint 检测配置文件步骤：

• 0. 在要检测的文件同一目录里寻找 .eslintrc.* 和 package.json；
• 0. 紧接着在父级目录里寻找，一直到文件系统的根目录；
• 0. 如果在前两步发现有 root：true 的配置，停止在父级目录中寻找 .eslintrc；
• 0. 如果以上步骤都没有找到，则回退到用户主目录 ~/.eslintrc 中自定义的默认配置；

通常我们都习惯把 ESLint 配置文件放到项目根目录，因此可以为了避免 ESLint 校验的时候往父级目录查找配置文件，所以需要在配置文件中加上 root: true。

{
    root: true,
}

参考：ESLint配置文件.eslintrc参数说明

如何配置

ESLint 支持 3 种配置方式：

• 命令行：不推荐，不做介绍；
• 单文件内注释：不推荐，不做介绍；
• 配置文件：配置文件的类型可以是好几种，比如：.js、.yml、json 等。推荐使用 .eslintrc.js，如果规则很少也可以配置在package.json当中。

0. 安装 npm i eslint -D

1. 初始化配置文件./node_modules/.bin/eslint --init 或者npx eslint --init都一样，会在根目录生成一个.eslintrc.js

2. 通过上面的介绍可以自己为自己配置一系列规则，那么我们如何触发呢？

   0. 校验单个文件

      npx eslint a.js b.js
      

   1. 校验一个目录

      npx eslint src
      

   2. 校验非js格式的文件，通常Eslint只能校验js文件，如果我们要校验.vue、.jsx文件该怎么做呢，只配置vue-eslint-parser的解析器是不够的，还需要让Eslint在查找文件的时候找得到.vue文件。可以通过--ext指定需要校验的文件格式

      npx eslint --ext .js,.jsx,.vue src  
      

   3. 在上面的规则当中进入官方文档的配置规则，在全部规则的列表里面带有标志的规则表示可以被Eslint自动修复，那么我们如何自动修复呢？只需要通过--fix的命名即可，和检验文件的命令相似，只需要再加上修复命令即可

      npx eslint --fix src
      

   4. 当然在项目中每次自己输入太过于繁琐也不好记，我们可以在package.json中配置检测和修复命令：

      {
          "scripts": {
              "lint": "npx eslint --ext .js,.jsx,.vue src",
              "lint:fix": "npx eslint --fix --ext .js,.jsx,.vue src",
          }
      }
      

   5. 过滤自己不需要检测的文件，在某些情况下我们不需要检测某些文件，或者由于某些原因在当前场景下不想去检测某个文件，我们只需要在项目根目录去创建.eslintignore文件，在其中指定目录或者文件即可，路径是以根目录为相对地址的路径。同时Eslint是默认忽略/node_modules/的文件的，这个目录不需要配置。

冷知识

0. sourceType 有两个值，script 和 module。 对于 ES6+ 的语法和用 import / export 的语法必须用 module.
1. eslint --init 只有在选择 "To check syntax, find problems, and enforce code style" 才可以选择 airbnb, standard, recommended 标准。
2. 有时候在前端项目中存在前端和 node 的代码共存的情况，只要在 env 中配置好 browser: true, node: true 就可以把兼容不同环境的全局变量兼容进来，例如 nodejs 中的 global, process 等等。
3. 规则强度是 airbnb > standard > recommended
4. 正常情况不会去修复一个文件，都会在项目上配置命令一次修复全局
5. 配合Prittier可以更好的工作
6. 配合Vscode实现自动保存，需要先下载Eslint插件，首选项 -> 设置 -> 搜索 "autofix". Auto Fix On Save。 就可以在保存的时候自动修正了。

总结

• eslint是干嘛的，如何生成使用，配置
• 如何配置规则，有哪些常用规则，如何触发
• 如何使用别人的开源规则，如何继承，如何修改继承的规则
• 如何使用插件，插件是干嘛用的，如何配合使用
• 如何去检测文件和自动修复文件以及配置检测修复命令
• 如何去检测非js格式的文件

对于基础入门我们只需了解这些知识就可以，在后续我们再来了解如何在Vue、React项目中引入Eslint及如何使用集成