如何使用ESLint？这是80%最常用的功能

你好同学，我是沐爸，欢迎点赞、收藏和关注！个人知乎、公众号"沐爸空间"

ESLint 是一个可配置的 JavaScript linter。它可以帮助开发者查找并修复 JavaScript 代码中的问题。通过这篇文章你可以掌握 ESLint 的基本使用、规则配置、规则禁用、文件忽略、工具集成，了解预定义全局变量和插件。

一、基本使用

安装依赖

npm i eslint -D

初始化配置

npx eslint --init

按照提示可以进行自定义配置，如前端框架vue或/react、是否使用TypeScript、使用场景browser/node，采用的包管理工具等，完成后生成配置文件 eslint.config.mjs:

import globals from "globals";
import pluginJs from "@eslint/js";
import pluginVue from "eslint-plugin-vue";

export default [
  {files: ["**/*.{js,mjs,cjs,vue}"]},
  {languageOptions: { globals: globals.browser }},
  pluginJs.configs.recommended, // ESLint推荐配置
  ...pluginVue.configs["flat/essential"] // Vue插件配置
];

注意：所有配置均需使用 eslint.config.mjs文件，老的 eslintrc.js 和 .eslintrc.json 已不再被支持。

配置脚本 package.json

"scripts": {
  "eslint": "eslint src",
  "eslint:fix": "eslint src --fix",
}

运行脚本

npm run eslint
npm run eslint:fix

运行完脚本就会在控制台看到不符合 ESLint 规范的错误提示。

二、预定义全局变量

预定义全局变量的作用是什么？比如说代码中使用了 document 变量，如果没有使用预定义配置，且 document 未定义，那么 document 就属于未定义使用，进而会触发警告。由此可以看出，预定义全局变量的作用是对部分变量进行放行，不再检测。

// eslint.config.js
import globals from "globals";

export default [
    {
        languageOptions: {
            globals: globals.browser
        }
    }
]

以 globals.browser 为例，它预定义了哪些全局变量呢？下面仅列出部分几个常见的，了解全部请查看 globals 安装包。

type GlobalsBrowser = {
	readonly 'addEventListener': false;
	readonly 'alert': false;
    readonly 'blur': false;
    readonly 'clearInterval': false;
	readonly 'clearTimeout': false;
    readonly 'console': false;
    readonly 'document': false;
}

三、插件

ESLint 虽然可以定义很多的 rules，但是它本身只是检查 JavaScript 语法。如果要检查 Vue 中的 template 或者React 中的 jsx 语法，它就不行了，但是插件可以。插件可以增强 ESLint 的检查能力和范围。

以上方基本应用中的 eslint.config.mjs 为例，"eslint-plugin-vue" 就是为了检测 Vue 文件而安装的插件，pluginVue.configs["flat/essential"] 中包含了 Vue 插件的配置和规则，打印结果如下：

[
  {
    name: 'vue:base:setup',
    plugins: { vue: [Getter] },
    languageOptions: { sourceType: 'module', globals: [Object] }
  },
  {
    name: 'vue:base:setup-for-vue',
    files: [ '*.vue', '**/*.vue' ],
    plugins: { vue: [Getter] },
    languageOptions: { parser: [Object], sourceType: 'module', globals: [Object] },
    rules: { 'vue/comment-directive': 'error', 'vue/jsx-uses-vars': 'error' },
    processor: 'vue/vue'
  },
  {
    name: 'vue:essential:rules',
    rules: {
      'vue/multi-word-component-names': 'error',
      'vue/no-arrow-functions-in-watch': 'error',
      'vue/no-async-in-computed-properties': 'error',
      'vue/no-child-content': 'error',
      'vue/no-computed-properties-in-data': 'error',
      'vue/no-deprecated-data-object-declaration': 'error',
      'vue/no-deprecated-destroyed-lifecycle': 'error',
      ......
    }
  }
]

需要自己创建插件的话，可以看这里：Create Plugins - ESLint - Pluggable JavaScript Linter

四、配置规则

要更改规则的严重性，请将规则 ID 设置为以下值之一：

• "off"或者0 - 关闭规则
• "warn"或者1 - 将规则作为警告打开（不会导致程序退出）
• "error"或者2 - 将规则作为错误打开（当被触发的时候，程序会退出）

例：

export default [
    {
        rules: {
            semi: "error" // 行尾需要分号
        }
    }
];

配置冲突时如何处理？当多个配置对象指定相同的规则时，规则将进行合并，后定义的配置会覆盖先定义的。

情形一：完全覆盖

export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    },
    {
        rules: {
            semi: ["warn", "always"]
        }
    }
];

合并后的配置为：semi: ["warn", "always"]

情形二：部分覆盖

export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    },
    {
        rules: {
            semi: ["warn"]
        }
    }
];

合并后的配置为：semi: ["warn", "never"]

五、禁用规则

如果某一个文件或某一行代码不要需要校验规则，或者需要临时关闭校验，该怎么处理呢？

1.使用配置文件

export default [
    {
        rules: {
            "semi": "error" // 全局生效，行尾需要分号
        }
    },
    {
        files: ["*.config.js"],
        rules: {
            "semi": "off" // 以.config.js结尾的文件关闭结尾分号校验
        }
    }
];

2.使用配置注释

首先要明确的是，最好使用 ESLint 配置文件，也就是上面的方式一，而不是禁用注释。

开发同学应该谨慎使用ESLint内联规则，尽量作为临时方案使用，使用时应提供一条注释，解释禁用特定规则的原因。

1.禁用文件的一部分代码

* eslint-disable */

alert('foo');

/* eslint-enable */

2.还可以禁用或启用特定规则的警告：

/* eslint-disable no-alert, no-console */

alert('foo');
console.log('bar');

/* eslint-enable no-alert, no-console */

3.禁用整个文件中的规则警告：

/* eslint-disable */

alert('foo');

4.可以禁用或启用整个文件的特定规则：

/* eslint-disable no-alert */

alert('foo');

5.禁用特定行上的所有规则，请使用以下格式之一的行或块注释：

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

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

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

alert('foo'); /* eslint-disable-line */

6.禁用特定行上的特定规则，请执行以下操作：

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

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

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

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

7.要在特定行上禁用多个规则：

alert('foo'); // eslint-disable-line no-alert, quotes, semi

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

alert('foo'); /* eslint-disable-line no-alert, quotes, semi */

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

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

8.关于注释说明

配置注释可以包含说明，以解释为什么需要禁用或重新启用规则。描述必须位于配置之后，并且需要用两个或多个连续字符与配置分隔。例如：

// eslint-disable-next-line no-console -- Here's a description about why this configuration is necessary.
console.log('hello');

/* eslint-disable-next-line no-console --
 * Here's a very long description about why this configuration is necessary
 * along with some additional information
**/
console.log('hello');

六、忽略文件

你可以通过以下方式忽略某些文件和目录：

1.忽略文件

// eslint.config.js
export default [
    {
      ignores: [".config/*", 'vue.config.js'],
    }
];

.config 目录下的所有文件和 vue.config.js 文件都将被忽略。

2.忽略目录

假如目录结构是这样的：

├── .config
│   ├── demo1.js
│   └── demo2.js
├── foo
│   └── .config
│       ├── demo3.js
│       └── demo4.js
└── eslint.config.js

忽略目录的工作方式与忽略文件的工作方式相同，以下代码将忽略整个目录（这意味着文件搜索根本不会遍历到其中）：

// eslint.config.js
export default [
    {
        ignores: [".config/"]
    }
];

上面的忽略模式只会忽略与配置文件 eslint.config.js 位于同一目录中的目录，只有demo1.js和demo2.js被忽略。如果要递归忽略所有已命中的目录，则需要使用 如下示例：

// eslint.config.js
export default [
    {
        ignores: ["**/.config/"]
    }
];

修改成上面的忽略模式后，.config和foo/.config目录下的文件都将被忽略。

3.不忽略文件和目录

你还可以取消忽略被先前模式（包括默认模式）忽略的文件和目录。例如，此配置取消忽略：

// eslint.config.js
export default [
    {
        ignores: [
            "!node_modules/",           // unignore `node_modules/` directory
            "node_modules/*",           // ignore its content
            "!node_modules/mylibrary/"  // unignore `node_modules/mylibrary` directory
        ]
    }
];

七、命令行

命令行包含很多内容，像基础配置、指定解析器、指定规则和插件、修复问题、忽略文件、输出和缓存等。这里只讲几个平时最常用的命令。

1.文件检测

# 运行两个文件
npx eslint file1.js file2.js

# 检测src和scripts目录
npx eslint src scripts

你也可以省略文件参数，ESLint 将使用 . 进行检测所有匹配文件，这两行执行相同的操作：

npx eslint .
npx eslint

2.指定文件类型

# 仅检测src下js文件
npx eslint src/**/*.js

老版本的 ESLint 可以通过 --ext 选项指定文件类型，下面这种方式目前已被弃用：

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

3.文件修复

npx eslint --fix file.js

--fix选项是 ESLint 提供自动修复基础错误的功能，它只能修复一些基础的不影响代码逻辑的错误，比如代码末尾加上分号、表达式的空格等。

八、集成

1.编辑器：Visual Studio Code：ESLint 扩展

ESLint 插件能够检测 JavaScript 中的语法错误和潜在的逻辑错误。如果代码中存在不符合规范的地方，ESLint 会在 VSCode 编辑器中直接显示错误或警告信息，帮助开发同学及时发现并修复问题。没有安装的话，赶紧安装试试吧。

2.源代码管理：Git 提交钩子

使用 Git 提交钩子可以进行代码检测和修复。上传代码前如何自动化修复 ESLint 错误，可以参考我的上一篇：如何利用ESLint、StyleLint、Prettie保持前端代码的一致性？