ESLint v8.51.0

ESLint 是一款流行的开源静态代码分析工具，用于 JavaScript。它帮助开发人员在代码中识别和修复潜在的问题，并强制执行编码风格约定。ESLint 基于配置文件中定义的一组规则对 JavaScript 代码进行分析，并提供反馈，指出语法错误、未使用的变量、潜在的错误和代码风格不一致等问题。

安装

shell

npm init @eslint/config

配置

文件格式

ESLint 支持几种格式的配置文件：

JavaScript：使用 .eslintrc.js 并导出包括配置的对象。
JavaScript (ESM)：当在 JavaScript 包中运行 ESLint 时，且其 package.json 中指定 "type":"module" 时，请使用 .eslintrc.cjs 文件(因为 ESLint 8.x 目前不支持 ESM 配置)。

// .eslintrc.cjs
module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:vue/vue3-essential'
  ],
  overrides: [
    {
      env: {
        node: true
      },
      files: ['.eslintrc.{js,cjs}'],
      parserOptions: {
        sourceType: 'script'
      }
    }
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    parser: '@typescript-eslint/parser',
    sourceType: 'module'
  },
  plugins: ['@typescript-eslint', 'vue'],
  rules: {}
}

YAML：使用 .eslintrc.yaml 或 .eslintrc.yml 来定义配置结构。ESLint YAML 文件中可以使用 JavaScript 风格注释。
JSON：使用 .eslintrc.json 来定义配置结构。ESLint JSON 文件中可以使用 JavaScript 风格注释。
package.json：在 package.json 文件中创建 eslintConfig 属性并自定义配置。

json

{
  "name": "your-project",
  "version": "1.0.0",
  "eslintConfig": {
    "env": {
      "browser": true,
      "node": true
    },
    "extends": [
      "eslint:recommended",
      "plugin:vue/essential" // 适用于 Vue 项目的配置示例
    ],
    "rules": {
      // 你的自定义规则
    }
  },
  "devDependencies": {
    // 你的依赖
  }
}

TIP

如果在同一目录下存在多个配置文件，ESLint 将按照以下优先顺序以此使用其一：

.eslintrc.js > .eslintrc.cjs > .eslintrc.yaml > .eslintrc.yml > .eslintrc.json > package.json

级联和层次结构

默认情况下，ESLint 将在所有父文件夹中寻找配置文件，直到根目录。如果你想让你的所有项目都遵循某个惯例，这可能很有用，但有时会导致意外的结果。要将 ESLint 限制在一个特定的项目中，在 .eslintrc.* 文件或 package.json 文件的 eslintConfig 字段内或在项目根层的 .eslintrc.* 文件中放置 "root": true。一旦 ESLint 找到 "root": true 的配置，它将停止在父文件夹中寻找。

环境

browser：浏览器全局变量。
node：Node.js 的全局变量和 Node.js 的范围。
commonjs：CommonJS 全局变量和 CommonJS 范围（用于使用 Browserify/WebPack 的纯浏览器代码）。
es6：启用除模块之外的所有 ECMAScript 6 功能，并自动将解析器选项 ecmaVersion 设置为 6。
jest：Jest 全局变量。

使用配置注释

在 JavaScript 文件中使用注释来指定环境，请使用以下格式：

/* eslint-env node, mocha */

使用配置文件

在 .eslintrc.* 文件中或者在 package.json 文件中使用 env 键指定环境，并通过将每个环境设置为 true 来启用想要的环境。

module.exports = {
  env: {
    browser: true,
    node: true
  }
}

全局变量

使用配置注释

默认为只读；若指定全局变量可以被写入，则需要加个 writable 。

/* global var1, var2:writable */

使用配置文件

json

{
  "globals": {
    "var1": "writable",
    "var2": "readonly"
  }
}

解析器

默认情况下，ESLint 使用 Espree 作为其解析器，也可以使用自定义的解析器。以下解析器与 ESLint 兼容：

Esprima
@babel/eslint-parser：使 Babel 解析器与 ESLint 兼容的的包装器。
@typescript-eslint/parser：一个将 TypeScript 转换为与 ESTree 兼容的形式的解析器，因此它可以在 ESLint 中使用。

json

{
  "parser": "@typescript-eslint/parser"
}

注意

当使用自定义的解析器时，仍然需要配置 parserOptions 属性，以便 ESLint 在默认情况下与 ECMAScript 5 中没有的功能正常工作。解析器都是用 parserOptions 来决定特性启用与否。

解析器选项

在 .eslintrc.* 文件中通过使用 parserOptions 属性设置解析器选项。

ecmaVersion：设置为 3、5（默认）、6、7、8、9、10、11、12 或 13，以指定你要使用的 ECMAScript 语法的版本。你也可以设置为 2015（6）、2016（7）、2017（8）、2018（9）、2019（10）、2020（11）、2021（12）或 2022（13）来使用基于年份的命名。你也可以设置 "latest" 来使用受支持的最新版本。
sourceType：设置为 "script"（默认值）或 "module"（如果代码是 ECMAScript 模块）。
allowReserved：允许使用保留字作为标识符（如果 ecmaVersion 为 3）。
ecmaFeatures：表示你想使用哪些额外的语言特性的对象。
globalReturn：允许全局范围内的 return 语句
- impliedStrict：启用全局严格模式（如果 ecmaVersion 是 5 或更高版本）
- jsx：启用 JSX

json

{
  "parserOptions": {
    "ecmaVersion": "latest",
    "parser": "@typescript-eslint/parser",
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  }
}

处理器

在 .eslintrc.* 文件中使用 processor 键指定处理器，用斜线连接插件名称和处理器名称的字符串。例如，下面启用了插件 a-plugin 提供的处理器 a-processor：

json

{
  "plugins": ["a-plugin"],
  "processor": "a-plugin/a-processor"
}

要为特定类型文件指定处理器，可以一起使用 overrides 键和 processor 键。例如，下面使用处理器 a-plugin/markdown 来处理 *.md 文件。

json

{
  "plugins": ["a-plugin"],
  "overrides": [
    {
      "files": ["*.md"],
      "processor": "a-plugin/markdown"
    }
  ]
}

规则

eqeqeq：这个规则表示“严格相等比较（===）”的使用情况。
curly：这个规则控制着 if 语句和循环语句是否需要使用花括号（{}）来包裹代码块。
quotes：这个规则用于控制字符串的引号风格。可选值为 "double" （默认值）要求尽可能使用双引号、"single" 要求尽可能使用单引号、"backtick" 要求尽可能使用反引号

TIP

"off" 或 0：禁用了该规则，即允许使用非严格相等比较（==）。
"warn" 或 1：启用并视作警告（不影响退出）
"error" 或 2：启用并视作错误（触发时退出代码为 1）

使用配置注释

/* eslint eqeqeq: "off", curly: 2 */

配置注释描述

配置注释可以包括描述，以解释为什么注释是必要的。描述必须出现在配置之后，并以两个或多个连续的 - 字符与配置分开。

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

使用配置文件

json

{
  "rules": {
    "eqeqeq": "off",
    "curly": "error",
    "quotes": ["error", "double"]
  }
}

插件

在 .eslintrc.* 文件中通过使用 plugins 属性设置插件。对于非作用域包和作用域包，都可以省略 eslint-plugin- 前缀。

json

{
  "plugins": [
    "jquery", // 等同于 eslint-plugin-jquery
    "@jquery/jquery", // 等同于 @jquery/eslint-plugin-jquery
    "@foobar" // 等同于 @foobar/eslint-plugin
  ]
}

TIP

ESLint 加载插件，等同于通过在配置文件中运行 require('eslint-plugin-pluginName') 。

使用插件

json

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

eslint-plugin-vue

Vue.js 的官方 ESLint 插件，用于检查 .vue 文件的 <template> 和 <script>，以及 .js 文件中的 Vue 代码，如查找语法错误，发现 Vue.js 指令的错误使用，查找 Vue.js 风格指南的违规行为。

安装

bash

npm install -D eslint-plugin-vue

配置：4 选 1

json

{
  "extends": [
    // 用于检查 Vue 单文件组件（.vue 文件）中的代码，并提供了一些基本的规则来确保代码质量和一致性
    "plugin:vue/base",

    // 包含了一组必要的 Vue 3 规则，以及防止错误或意外行为的规则
    "plugin:vue/vue3-essential",

    // 包含了一组推荐的 Vue 3 规则，以及可显著提高代码可读性和/或开发体验的规则
    "plugin:vue/vue3-recommended",

    // 包含了一组强烈推荐的 Vue 3 规则，加上强制执行主观社区默认值以确保一致性的规则
    "plugin:vue/vue3-strongly-recommended"
  ]
}

解析器

如果您想使用自定义解析器，例如 @babel/eslint-parser 或 @typescript-eslint/parser，则必须使用 parserOptions.parser 选项而不是 parser 选项。因为这个插件需要 vue-eslint-parser 来解析 .vue 文件，所以如果你覆盖解析器选项，这个插件将不起作用。

json

 "parser": "vue-eslint-parser",
  "parserOptions": {
     "parser": "@typescript-eslint/parser",
      "sourceType": "module"
  }

eslint-config-prettier

用于与 Prettier 配合使用，以确保 ESLint 不会与 Prettier 冲突。具体来说，它的作用是禁用 ESLint 中与 Prettier 有冲突的规则，以允许 Prettier 格式化代码而不会引起 ESLint 报错。

安装

bash

npm install -D eslint-config-prettier

配置

json

{
  "extends": ["prettier"]
}

特殊规则

"arrow-body-style": 用于指定箭头函数的主体风格。具体来说，它规定了是否应该使用大括号 {} 包围箭头函数的主体（函数体）。

{
  "rules": {
    "arrow-body-style": ["error", "as-needed"]
  }
}

这个规则有三个选项

"always"（默认）：要求始终使用大括号 {} 包围箭头函数的主体，即使它只有一条语句。
"as-needed"：只有当箭头函数的主体包含多条语句时，才需要使用大括号 {} 包围。如果箭头函数只有一条语句，可以省略大括号。
"never"：始终不使用大括号 {} 包围箭头函数的主体，即使它有多条语句。这个选项通常会导致单行箭头函数。

"prefer-arrow-callback": 用于指定在函数表达式中是否应该优先使用箭头函数。

{
  "rules": {
    "prefer-arrow-callback": ["error", "as-needed"]
  }
}

这个规则有一个选项

"always"（默认）：要求在函数表达式中始终使用箭头函数。这意味着你应该使用箭头函数来定义回调函数，而不是传统的函数表达式。
"as-needed"：允许在函数表达式中使用箭头函数，但只有在以下情况下才需要使用：

当回调函数不引用当前作用域中的任何变量时。
当回调函数不使用 this 关键字时。

在其他情况下，你可以使用传统的函数表达式。

DANGER

当配置了 arrow-body-style 和 prefer-arrow-callback 特殊规则，则如果使用 eslint-plugin-prettier 插件和 --fix 命令可能会生产一些问题，此时应该将其进行关闭（参考 eslint-plugin-prettier 章节的推荐配置）。

"curly": 用于控制 if、else if、else、for、while 和 do...while 语句是否需要使用花括号 {} 来包裹代码块。

{
  "rules": {
    "curly": ["error", "multi"]
  }
}

这个规则有三个选项

"all"（默认）：要求使用大括号 {} 包裹所有的 if、else if、else、for、while 和 do...while 语句中的代码块，无论代码块的内容是单行还是多行。
"multi"：要求只有在代码块包含多行语句时才需要使用大括号 {}，而单行语句的代码块可以省略大括号。
"multi-line"：要求只有在代码块包含多行语句时才需要使用大括号 {}，单行语句的代码块也需要使用大括号，但仅限于 if、else if、else 语句中。

"lines-around-comment": 用于控制在注释周围是否需要添加空行。

{
  "rules": {
    "lines-around-comment": ["error", "before"]
  }
}

这个规则有三个选项

"before"：要求在注释前面有一个空行。也就是说，在注释之前必须有一个空行分隔注释和之前的代码。
"after"：要求在注释后面有一个空行。也就是说，在注释之后必须有一个空行分隔注释和之后的代码。
"both"：要求在注释前后都有一个空行，即在注释前后都必须有一个空行。

"max-len": 用于控制单行代码的最大字符长度限制。

{
  "rules": {
    "max-len": ["error", { "code": 100, "ignoreComments": true }]
  }
}

这个规则有多个选项

"off"（默认）：禁用此规则，不进行字符长度的检查。
"error"：启用此规则，将会对单行代码的字符长度进行检查，并根据配置的值来判断是否超出限制。
"warn"：与 "error" 类似，但不会导致 ESLint 报错，而是产生警告。
{ "code": number, "tabWidth": number, "ignoreUrls": true/false, "ignoreStrings": true/false, "ignoreTemplateLiterals": true/false, "ignoreComments": true/false, "ignoreTrailingComments": true/false, "ignoreUrls": true/false }：

"code"：指定允许的最大字符数。
"tabWidth"：指定一个制表符的宽度，通常为 4 或 2。
"ignoreUrls"：是否忽略 URL。
"ignoreStrings"：是否忽略字符串。
"ignoreTemplateLiterals"：是否忽略模板字面量。
"ignoreComments"：是否忽略注释。
"ignoreTrailingComments"：是否忽略位于行尾的注释。

"no-confusing-arrow": 用于防止箭头函数的语法产生混淆或不明确的情况。

{
  "rules": {
    "no-confusing-arrow": "error"
  }
}

这个规则有一个选项

"allowParens"：默认为 false，表示不允许箭头函数使用括号包裹参数。如果设置为 true，则允许使用括号包裹参数。

"no-mixed-operators": 用于防止在表达式中混合使用不同的操作符时引起的混淆。

这个规则有一个选项

"groups"：一个配置对象，用于指定哪些操作符可以混合使用。可以配置的操作符组包括：

"and"：表示逻辑与操作符 (&&) 与位操作符 (&)。
"or"：表示逻辑或操作符 (||) 与位操作符 (|)。
"equals"：表示相等操作符 (===, !==) 与关系操作符 (<, <=, >, >=)。
"lessThan"：表示关系操作符 (<, <=) 与位操作符 (&, |)。
"greaterThan"：表示关系操作符 (>, >=) 与位操作符 (&, |)。
"plus"：表示加法操作符 (+) 与位操作符 (&, |)。

"no-tabs": 用于禁止在代码中使用制表符（Tab 字符），并要求使用空格来进行缩进。

{
  "rules": {
    "no-tabs": "error"
  }
}

这个规则有一个选项

"allowIndentationTabs"：默认为 false，表示不允许在缩进中使用制表符。如果设置为 true，则允许在缩进中使用制表符。

"no-unexpected-multiline": 用于防止发生不明确的多行代码错误。

{
  "rules": {
    "no-unexpected-multiline": "error"
  }
}

"quotes": 用于指定在代码中使用的引号类型，例如单引号 (') 或双引号 (")。

{
  "rules": {
    "quotes": ["error", "double", { "avoidEscape": true }]
  }
}

这个规则有三个选项

"single"：要求在代码中使用单引号。
"double"：要求在代码中使用双引号。
"backtick"：要求在代码中使用反引号（模板字面量）。
{ "avoidEscape": true, "allowTemplateLiterals": true }：

"avoidEscape"：默认为 true，表示应避免使用需要转义的引号。例如，如果该选项为 true，则在字符串中使用双引号时，如果字符串本身包含双引号，则会报告错误。
"allowTemplateLiterals"：默认为 false，表示是否允许在代码中使用模板字面量。如果设置为 true，则允许使用反引号，但仍要求字符串内部的插值部分使用 ${} 包围。

"vue/html-self-closing": 用于控制 Vue.js 单文件组件（.vue 文件）中自闭合标签（self-closing tags）的使用。

{
  "rules": {
    "vue/html-self-closing": "always"
  }
}

这个规则有二个选项

"always"：默认值，要求始终使用自闭合标签，即使标签没有属性。
"never"：要求始终不使用自闭合标签，而是使用完整的标签形式，即使标签没有属性。

"no-sequences": 用于禁止在 JavaScript 代码中使用逗号操作符（,）创建表达式序列。

{
  "rules": {
    "no-sequences": "error"
  }
}

eslint-plugin-prettier

安装

bash

npm install -D eslint-plugin-prettier

配置

json

{
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }
}

推荐配置

当安装 eslint-config-prettier 插件时必须使用该配置，否则会发生问题。

json

{
  "extends": ["plugin:prettier/recommended"]
}

// 等效于
{
  "extends": ["prettier"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error", // 启用 prettier 规则
    "arrow-body-style": "off",
    "prefer-arrow-callback": "off"
  }
}

忽略文件

在配置文件中添加 ignorePatterns 属性。
创建包括忽略匹配模式的专用文件（默认为 .eslintignore）。

ignorePatterns

json

{
  "ignorePatterns": ["temp.js", "**/vendor/*.js"]
}

TIP

ignorePatterns 中的 glob 模式是相对于配置文件所在的目录而言的。
不能在 overrides 属性中使用 ignorePatterns 属性。
在 .eslintignore 中定义的模式优先于配置文件的 ignorePatterns 属性。

.eslintignore

bash

node_modules
cache
dist
/src/*.js

使用替代文件

bash

eslint --ignore-path .gitignore

注意

指定 --ignore-path 意味着任何现有的 .eslintignore 文件将不会被使用。

package.json 中的 eslintIgnore

json

{
  "name": "mypackage",
  "version": "0.0.1",
  "eslintConfig": {
    "env": {
      "browser": true,
      "node": true
    }
  },
  "eslintIgnore": ["hello.js", "world.js"]
}

在 package.json 的 script 中添加命令

json

"scripts": {
    "lint": "eslint . --ext .vue,.js,.cjs,.mjs,.ts --fix --ignore-path .gitignore"
  }

ESLint v8.51.0 ​

安装 ​

配置 ​

文件格式 ​

级联和层次结构 ​

环境 ​

使用配置注释 ​

使用配置文件 ​

全局变量 ​

使用配置注释 ​

使用配置文件 ​

解析器 ​

解析器选项 ​

处理器 ​

规则 ​

使用配置注释 ​

使用配置文件 ​

插件 ​

使用插件 ​

eslint-plugin-vue ​

eslint-config-prettier ​

eslint-plugin-prettier ​

忽略文件 ​

ignorePatterns ​

.eslintignore ​

使用替代文件 ​

package.json 中的 eslintIgnore ​

在 package.json 的 script 中添加命令 ​

ESLint v8.51.0

安装

配置

文件格式

级联和层次结构

环境

使用配置注释

使用配置文件

全局变量

使用配置注释

使用配置文件

解析器

解析器选项

处理器

规则

使用配置注释

使用配置文件

插件

使用插件

eslint-plugin-vue

eslint-config-prettier

eslint-plugin-prettier

忽略文件

ignorePatterns

.eslintignore

使用替代文件

package.json 中的 eslintIgnore

在 package.json 的 script 中添加命令