简介
ESLint 是一个可配置的 JavaScript 和JSX代码检查工具，其目的是使代码风格更加一致并避免错误，使得项目规范化。
JSX（JavaScript XML）是 JavaScript 的语法扩展，主要用于 React 框架中描述用户界面。
它允许开发者在 JavaScript 代码中直接编写类似 HTML 的标记。
最终会被编译为标准的 JavaScript 函数调用（如 React.createElement()）。
例：const element = <span>Hello, JSX!</span>;
执行流程
- 解析命令行参数和配置文件（初始化阶段）
- 递归查找目标目录或文件（文件遍历阶段）
- 依赖Espree转换源代码为抽象语法树（AST）（文件解析阶段）
- 遍历AST，触发规则检查，报告问题严重级别（规则应用阶段）
- 汇总并输出结果（结果收集阶段）
- Espree一个基于 ECMAScript 标准的 JavaScript 解析器，由 ESLint 团队开发并维护。它主要用于将 JavaScript 代码解析为抽象语法树（AST），以便进行静态分析或代码转换。Espree 最初是从 Acorn 派生而来，但经过优化以适应 ESLint 的需求。
- 工作流程：代码文本经过词法分析生成Token流，语法分析器将Token转换为AST。遍历AST时，eslint调用所有启用规则对节点进行检查。规则通过上下文API访问节点信息，最终生成包含错误位置和描述的报表。
核心原理
为静态代码分析，通过规则集对代码进行模式匹配和抽象语法树（AST）解析，从而发现潜在问题或风格违规。
静态分析：不执行代码，直接读取源码文本，通过ESpree转换为能精确描述代码语法关系的树状结构(AST)。AST包括代码的：类型、位置、变量等元信息
规则引擎：每条eslint规则是一个独立的检查模块，接收AST节点作为输入。规则会对特定语法模式进行检测。
抽象语法树:树状结构
规范等级
根据配置的格式（如stylish、json）输出到控制台或文件。严重级别(数字或者英文均可)分为：
- 0(off)：关闭
- 1(warn)：警告
- 2(error)：错误
安装执行
本篇配置为传统配置，非扁平化配置。
安装
官网写法
npm init -y
npm init @eslint/config
交互式向导选择：
√ What do you want to lint? · javascript
√ How would you like to use ESLint? · problems
√ What type of modules does your project use? · commonjs
√ Which framework does your project use? · vue
√ Does your project use TypeScript? · no / yes
√ Where does your code run? · browser
The config that you've selected requires the following dependencies:
eslint, @eslint/js, globals, eslint-plugin-vue
√ Would you like to install them now? · No / Yes
√ Which package manager do you want to use? · npm
或者执行
npm init -y
npm i eslint -D
npx eslint --init
npm init -y 初始化package.json文件
npm i eslint -D 在生产环境安装依赖eslint
npx eslint --init 初始化 ESLint 配置文件的命令。运行该命令会启动一个交互式向导，帮助用户根据项目需求快速生成 ESLint 配置文件（通常是 .eslintrc.js 或 .eslintrc.json）
执行检查
单个文件
npx eslint ./js/index.js
整个项目
在 package.json 中添加属性"scripts": { "lint": "eslint ."}
npm run lint
Eslint规范
eslint的规则在node_modules\eslint\lib\rules文件夹中，文件夹下的每一条就是一个规则。
官方推荐的规则集在node_modules\@eslint\js\src\configs文件夹中。
@eslint/js 是 ESLint 官方提供的 JavaScript 配置包，用于提供预定义的 ESLint 规则集，帮助开发者快速配置代码检查规则。
配置文件格式
ESLint 支持几种格式的配置文件：
- JavaScript ：使用 .eslintrc.js 并导出包括配置的对象。
- JavaScript (ESM) ：当在 JavaScript 包中运行 ESLint 时，且其
package.json中指定"type":"module"时，使用 .eslintrc.cjs。请注意 ESLint 目前不支持 ESM 配置。 - YAML ：使用 .eslintrc.yaml 或 .eslintrc.yml 来定义配置结构。
- JSON ：使用 .eslintrc.json 来定义配置结构。ESLint JSON 文件中也可以使用 JavaScript 风格注释。
- package.json ：在 package.json 文件中创建 eslintConfig 属性并在那里定义你的配置。
如果在同一目录下有 .eslintrc 和 package.json 文件，.eslintrc 将优先使用，package.json 文件将不被使用。
常用配置
官网配置示例
JSON 配置文件示例，它使用了 typescript-eslint 解析器来支持 TypeScript 语法。
{
// 标识为 ESLint 根配置文件（停止向上查找父级配置）
root: true,
// 继承 ESLint 和 TypeScript 推荐规则集
extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
parser: "@typescript-eslint/parser", // 使用 TypeScript 专用解析器
parserOptions: { project: ["./tsconfig.json"] }, // 指定 tsconfig 路径用于类型信息解析
plugins: ["@typescript-eslint"], // 加载 TypeScript 插件
rules: {
"@typescript-eslint/strict-boolean-expressions": ["error",
{
allowString: false, // 禁止字符串自动转布尔
allowNumber: false, // 禁止数字自动转布尔
},
],
},
ignorePatterns: ["src/**/*.test.ts", "src/frontend/generated/*"], // 忽略测试文件和生成文件
}
JavaScript 格式的配置文件
扩展 eslint:recommended 并覆盖了一些配置选项。
module.exports = {
"extends": "eslint:recommended",
"rules": {
// 启用额外规则
"indent": ["error", 4],
"linebreak-style": ["error", "unix"],
"quotes": ["error", "double"],
"semi": ["error", "always"],
// override configuration set by extending "eslint:recommended"
"no-empty": "warn",
"no-cond-assign": ["error", "always"],
// 禁用基础配置汇总的规则
"for-direction": "off",
}
}
Vue ESlint示例配置(AI生成)
以下是一个适用于 Vue 项目的常用 ESLint 配置文件（.eslintrc.js），支持 Vue 3 和 TypeScript。
安装依赖包
npm install -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-vue @vue/eslint-config-typescript prettier eslint-config-prettier eslint-plugin-prettier
编辑器集成建议：
在 VS Code 中安装以下插件：ESLint、Prettier - Code formatter、Volar (Vue 语言支持)。
并在设置中启用保存时自动修复：
{
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
}
module.exports = {
root: true,
env: {
node: true,
browser: true,
es2021: true
},
extends: [
'eslint:recommended',//ESLint 官方推荐规则
'plugin:vue/vue3-recommended',//Vue 3 官方推荐规则
'@vue/typescript/recommended',//Vue 项目的 TypeScript 支持
'prettier'//避免与 Prettier 格式化冲突
],
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module'
},
rules: {
'vue/multi-word-component-names': 'off',//关闭组件名必须多单词的要求
'vue/require-default-prop': 'off',//关闭 props 必须设置默认值的要求
'vue/singleline-html-element-content-newline': 'off',//
'vue/max-attributes-per-line': [//限制每行 HTML 元素上允许的最大属性数量
'error',
{
singleline: 3,// 单行模式最大属性数
multiline: 1// 多行模式每行1个属性
}
],
'@typescript-eslint/no-explicit-any': 'off',// 允许使用 any 类型
'@typescript-eslint/no-unused-vars': [
'error',
{
argsIgnorePattern: '^_',
varsIgnorePattern: '^_'
}
],
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'//生产环境禁止调试代码
}
}
配套的 Prettier 配置：
在项目根目录创建 .prettierrc.js 与 ESLint 配合使用：
module.exports = {
semi: true,//在语句末尾自动添加分号
singleQuote: true,//强制使用单引号而非双引号包裹字符串，统一代码风格
printWidth: 100,//每行代码的最大宽度限制为100字符，超出时将自动换行格式化
tabWidth: 2,//缩进宽度设置为2个空格
trailingComma: 'none',//禁止在对象或数组最后一项后添加尾随逗号，如 {a:1, b:2} 而非 {a:1, b:2,}
arrowParens: 'avoid',//当箭头函数仅有一个参数时省略括号，例如 x => x+1 而非 (x) => x+1
endOfLine: 'auto'//自动识别并适配操作系统的换行符（CRLF/LF），确保跨平台一致性
}
root
默认情况下，ESLint 将在所有父文件夹中寻找配置文件，直到根目录。如果你想让你的所有项目都遵循某个惯例，这可能很有用，但有时会导致意外的结果。要将 ESLint 限制在一个特定的项目中，在 .eslintrc.* 文件或 package.json 文件的 eslintConfig 字段内或在项目根层的 .eslintrc.* 文件中放置 “root”: true。一旦 ESLint 找到 “root”: true 的配置，它将停止在父文件夹中寻找。
import { defineConfig } from "eslint/config";
export default defineConfig([
{
"root": true
}
]}
配置语言选项
env 指定环境
在配置文件中使用 env 键指定环境，并通过将每个环境设置为 true 来启用想要的环境。例如，下面是启用浏览器和 Node.js 环境的例子：
{
"env": {
"browser": true,
"node": true,
"es6":true,
}
}
要仅支持 ES6 语法，请使用 { “parserOptions”: { “ecmaVersion”: 6 } }，要同时支持 ES6 语法和新的 ES6 全局变量，如 Set 等，请使用 { “env”: { “es6”: true } }
globals 配置全局变量
包含为你要使用的每个全局变量命名的键。对于每个全局变量的键，将相应的值设置为 “writable” 以允许变量被覆盖，或者 “readonly” 以禁止覆盖。
在一个环境中，可以使用大多数 ES2015 全局变量，但不可以使用 Promise，则设置"Promise": "off"。
布尔值 false 和字符串值 “readable” 等同于 “readonly”。同样地，布尔值 true 和字符串"writeable" 等同于 “writable”。但是旧值已废弃。
{
"globals": {
"var1": "writable",
"var2": "readonly",
"Promise": "off"
}
}
parserOptions 指定解析器选项
{
"parserOptions": {
"ecmaVersion": "latest",//或2015（6）、2016（7）...2023（14)
"sourceType": "module",//设置为 "script"（默认值）或 "module"（如果代码是 ECMAScript 模块）。
/*
*ecmaFeatures 表示你想使用哪些额外的语言特性的对象
*globalReturn - 允许全局范围内的 return 语句
*impliedStrict - 启用全局严格模式（如果 ecmaVersion 是 5 或更高版本）
*jsx - 启用 JSX
*/
"ecmaFeatures": {
"jsx": true
}
},
"rules": {
"semi": "error"
}
}
plugins 插件配置
非范围包和范围包中都可以省略 eslint-plugin- 前缀。
{
"plugins": [
"plugin1",
"eslint-plugin-plugin2",
"jquery", // eslint-plugin-jquery
"@foo/foo", // @foo/eslint-plugin-foo
"@bar", // @bar/eslint-plugin
"a-plugin"
],
"processor": "a-plugin/a-processor"//指定处理器，启用了插件 a-plugin 提供的处理器 a-processor
}
rules规则配置
规则是 ESLint 的核心构建模块。规则验证你的代码是否符合某个期望，以及如果不符合该期望该怎么做。
import { defineConfig } from "eslint/config";
export default defineConfig([
{
rules:{
"no-unused-vars": "warn",//变量未使用
"no-console": "off",//禁止console
"no-sparse-arrays": "warn",//禁止稀疏数组，[1,,2]
"no-undef": "error",//禁止未定义变量
"no-unreachable":"error",//禁止不必要的跳过代码 例return后接代码
"no-dupe-keys": "error",//禁止对象字面量中出现重复的键 {a:1,a:2}
"semi": ["error", "always"],//强制代码中必须使用分号（;`）
/*
*覆盖基础配置中作为对象给出的规则的选项
*max设定文件最大行数为 200 行
*skipBlankLines计算行数时忽略空行
*skipComments计算行数时忽略注释行
*/
"max-lines": ["error", { "max": 200, "skipBlankLines": true, "skipComments": true }]
}
}
]}
规则参考：https://zh-hans.eslint.org/docs/latest/rules/
插件规则
要配置定义在插件中的规则，你必须在规则 ID 前加上插件的名称和 /。
import { defineConfig } from "eslint/config";
export default defineConfig([
{
"plugins": [
"plugin1"
],
"rules": {
"no-sparse-arrays": "off",
"plugin1/rule1": "error"
}
}
]}
禁用规则
此时仅列出了部分常用，剩余的查看此处。
要在文件的一部分中禁用规则警告，可以使用以下格式的块状注释：
/* eslint-disable */
alert('foo');
/* eslint-enable */
禁用或启用特定规则的警告
/* eslint-enable */ 没有列出任何特定的规则将导致所有被禁用的规则被重新启用。
/* eslint-disable no-alert, no-console */
alert('foo');
console.log('bar');
/* eslint-enable no-alert, no-console */
要禁用整个文件中的规则警告
/* eslint-disable */
alert('foo');
在整个文件范围内禁用或启用特定规则
/* eslint-disable no-alert */
alert('foo');
extends 继承
plugins 属性值可以省略包名中的 eslint-plugin- 前缀。react 是 eslint-plugin-react
import { defineConfig } from "eslint/config";
export default defineConfig([
{
extends: [
"eslint:recommended",
"plugin:react/recommended"
],
"rules": {
"react/no-set-state": "off"
}
}
]}
extends 属性值可以是：
- 一个指定配置的字符串。
- 一个指定配置的字符串（要么是配置文件的路径，要么是可共享配置的名称，要么是 eslint:recommended，要么是 eslint:all）。
- 一个字符串数组，每个额外的配置都会扩展前面的配置。
rules里自定义的规则高于extends继承的规则
- Eslint官方的规则区：eslint:recommended（官方推荐不需要下载）
- Vue cli官方的规则区：plugin:vue/essential
- React Cli 官方的规则区： react-app
其他第三方规则集：antfu、Airbnb、Google、Standard
可以省略配置名称中的 eslint-config- 前缀'。如 airbnb 会被解析为 eslint-config-airbnb。
antfu:
npm install -D eslint @antfu/eslint-config
创建或修改 .eslintrc 配置文件，继承 antfu 的预设：{"extends": "@antfu"}
overrides 基于 glob 模式的配置
通过使用 overrides 键，可以覆盖配置中基于文件 glob 模式的设置。比如同一目录下的文件的配置不同。
使用 overrides 键的示例：
在你的 .eslintrc.json 中：
{
"rules": {
"quotes": ["error", "double"]
},
"overrides": [
{
"files": ["bin/*.js", "lib/*.js"],
"excludedFiles": "*.test.js",
"rules": {
"quotes": ["error", "single"]
}
}
]
}
ignorePatterns 忽略文件
不能在 overrides 属性中使用 ignorePatterns 属性。
在 .eslintignore 中定义的模式优先于配置文件的 ignorePatterns 属性。
{
"ignorePatterns": ["temp.js", "**/vendor/*.js"],
}
.eslintignore 文件
在项目的根目录下创建 .eslintignore 文件来告诉 ESLint 要忽略哪些文件和目录。.eslintignore 文件是一个纯文本文件，其中每一行都是一个 glob 模式。
**/*.js
node_modules/
files 文件配置
配置eslint检查哪些类型的文件。（文档中没看到，不确定是否已废弃）
import { defineConfig } from "eslint/config";
export default defineConfig([
{
files:["**/*.{js,mjs,cjs,vue}"]
}
]}
webpack中使用eslint
npm install eslint eslint-webpack-plugin --save-dev
项目规范化
- 解释：确保团队在项目开发过程中遵循统一的技术、风格、结构及代码质量标准。
- 包含：代码风格(变量、函数命名规则)、文件命名(命名统一)、目录结构(如何组织项目目录和文件)、提交规范(代码提交时的信息结构)等多个方面。
- 目的：项目规范化的目的是提高项目的可维护性、一致性和可读性，减少团队成员之间的沟通障碍。
- 优势：有助于团队成员快速上手，减少Bug，并提升项目的可扩展性。
其他扩展
在扩展工具中安装Error Lens扩展插件，可在代码中看到错误提示。
参考链接：
中文Eslint文档
ESLint机制浅析-整体机制与规范
视频链接：
尚硅谷Webpack5中Eslint部分
Eslint