ESLint

第一章：初识

ESLint 是查找 JS 代码中的问题并修复的。

使用 ESLint，关键是写 ESLint 配置文件，里面写上各种 rules 规则，之后在运行 ESLint 时就会以写的规则对代码进行检查。

官方网站：ESLint 文档

民间中文网：

• ESLint 中文网
• ESLint

第二章：配置 ESLint

一、配置文件

方法一：新建配置文件，位于项目根目录。

// 任选其一 (优先级从大到小)
eslint.config.js
eslint.config.mjs
eslint.config.cjs
eslint.config.ts
eslint.config.mts
eslint.config.cts

方法二：package.json 中添加 eslintConfig 字段。自 ESLint v9.0.0 以来，只支持单独的配置文件。

注意：ESLint 会查找和自动读取它们，所以以上配置文件只需要存在一个即可。

二、配置对象

以 eslint.config.js 配置文件为例：

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([ // 数组里每个 item 是配置对象
  {
    // 配置语言选项
    languageOptions: {},
    // 具体检查规则
    rules: {},
    // 继承其他规则
    extends: [],
    // ...
  },
  {} // 配置对象可以是多个
]);

注意：如果其 package.json 文件中没有指定 "type":"module"，则 eslint.config.js 必须是 CommonJS 格式。

基础

name - 配置对象的名称。用于优化错误提示。

检查哪些文件？

basePath - 定位这些文件的基础目录。

files - 告诉 ESLint 这个配置对象适用于哪些文件。

ignores - 告诉 ESLint 忽略哪些文件。

代码环境

languageOptions：告诉 ESLint 你的代码处于什么环境，怎么解析。

工具与扩展

extends - 继承别人写好的配置包。

plugins - 引入第三方插件。比如检查 React 代码需要引入 React 插件、检查 Vue 代码引入 Vue 插件。

processor - 处理器。比如你想检查 .md 文件或者 .html 文件里面包裹的 <script> 代码，就需要处理器把 JS 代码先“提取”出来。

规则与设置

rules - 最核心的地方，具体开启或关闭哪些代码检查规则（比如 "no-unused-vars": "error" 表示定义了但没使用的变量要报错）。

linterOptions - ESLint 工具自身的设置。例如 noInlineConfig 如果设为 true，程序员在代码里写 // eslint-disable-next-line 企图强行无视报错就不管用了。

settings - 全局共享的设置信息，供下面的具体规则读取（比如告诉 React 插件你用的是 React 18 版本）。

三、具体配置

1. 配置语言选项

1）代码运行环境

// eslint.config.js
import { defineConfig } from "eslint/config";
import globals from "globals";

export default defineConfig([
  {
    languageOptions: {
      globals: {
        ...globals.browser, // 浏览器
        ...globals.node, // Node.js
      },
    },
  },
]);

2）指定 JavaScript 选项

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    languageOptions: {
      ecmaVersion: "latest",     // ECMAScript 版本
      sourceType: "module",      // 正在使用的 JavaScript 文件的模式。取值: module、commonjs、script
    },
  },
]);

3）指定解析器选项

更改 ESLint 解释代码的方式。

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    languageOptions: {
      parserOptions: {
        allowReserved: false,     // 允许使用保留字作为标识符
        ecmaFeatures: {           // 指示你要使用哪些附加语言功能
          globalReturn: false,    // 允许全局作用域内的 return 语句
          impliedStrict: true,    // 启用全局严格模式
          jsx: true,              // 如果是 React 项目，就需要开启 jsx 语法
        },
      },
    },
  },
]);

4）指定全局变量

使用配置注释

// 定义了两个全局变量，var1 和 var2
/* global var1, var2 */

// 全局变量可以被写入（而不仅仅是被读取），那么可以为每个变量设置一个 "writable" 标志
/* global var1:writable, var2:writable */

使用配置文件

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    languageOptions: {
      globals: {
        var1: "writable",
        var2: "readonly",
      },
    },
  },
]);

5）配置解析器

ESLint 的工作原理是先将代码进行解析，然后按照规则进行分析。

ESLint 默认使用 Espree 作为其解析器，你可以在配置文件中指定一个不同的解析器。

// eslint.config.js
import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.mjs"],
    languageOptions: {
      parser: babelParser,  // 配置自定义解析器
      parserOptions: {      // 传递给自定义解析器的选项, 需要查阅正在使用的解析器的文档以获取可用选项
        requireConfigFile: false,
        babelOptions: {
          babelrc: false,
          configFile: false,
          presets: ["@babel/preset-env"],
        },
      },
    },
  },
]);

2. 配置规则

1）rules 具体规则

• "off" 或 0 - 关闭规则。
• "warn" 或 1 - 当代码违反该规则时，ESLint 会产生一个警告，但不会导致程序退出。
• "error" 或 2 - 当代码违反该规则时，ESLint 会产生一个错误，且程序会退出。

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    rules: {
      eqeqeq: "off",
      "no-unused-vars": "error",
      "prefer-const": ["error", { ignoreReadBeforeAssign: true }],
    },
  },
]);


rules: {
  semi: "error", // 要求在每个语句的末尾都必须使用分号
  'array-callback-return': 'warn', // 强制数组方法的回调函数中有 return 语句，否则警告
  'default-case': [
    'warn', // 要求 switch 语句中有 default 分支，否则警告
    { commentPattern: '^no default$' } // 允许在最后注释 no default, 就不会有警告了
  ],
  eqeqeq: [
    'warn', // 强制使用 === 和 !==，否则警告
    'smart' // https://eslint.nodejs.cn/docs/rules/eqeqeq#smart 除了少数情况下不会有警告
  ],
}

更多规则详见：规则文档

2）extends 继承

开发中一点点写 rules 规则太费劲了，所以有更好的办法，继承现有的规则。

现有以下较为有名的规则：

• Eslint 官方的规则：eslint:recommended【过时】
• Vue Cli 官方的规则：plugin:vue/essential
• React Cli 官方的规则：react-app

ESLint 预设规则

ESLint 有两个预定义的 JavaScript 配置：

• js/recommended - 启用 ESLint 建议每个人都使用的规则以避免潜在错误。
• js/all - 启用 ESLint 附带的所有规则。不建议将此配置用于生产，因为它会随着 ESLint 的每个小版本和主要版本而变化。

要包含这些预定义配置，请安装 @eslint/js 包，然后对后续配置对象中的其他属性进行任何修改：

// eslint.config.js
import js from "@eslint/js";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: {
      js,
    },
    extends: ["js/recommended"], // 等价写法: js.configs.recommended,
    rules: {
      "no-unused-vars": "warn",
    },
  },
]);

这些规则使用前都需要先安装。

// 例如在React项目中，我们可以这样写配置
module.exports = {
  extends: ["react-app"],
  rules: {
    // 我们的规则会覆盖掉react-app的规则
    // 所以想要修改规则直接改就是了
    eqeqeq: ["warn", "smart"],
  },
};

第三章：集成

一、在 webpack 中使用

1）下载包

npm i eslint-webpack-plugin eslint -D

2）定义 Eslint 配置文件 .eslintrc.js

module.exports = {
  // 继承 Eslint 规则
  extends: ["eslint:recommended"],
  env: {
    node: true, // 启用node中全局变量
    browser: true, // 启用浏览器中全局变量
  },
  parserOptions: {
    ecmaVersion: 6,
    sourceType: "module",
  },
  rules: {
    "no-var": 2, // 不能使用 var 定义变量
  },
};

3）修改 js 文件代码 main.js

import count from "./js/count";
import sum from "./js/sum";
// 引入资源，Webpack才会对其打包
import "./css/iconfont.css";
import "./css/index.css";
import "./less/index.less";
import "./sass/index.sass";
import "./sass/index.scss";
import "./styl/index.styl";

// 新添加的
var result1 = count(2, 1);
console.log(result1);
var result2 = sum(1, 2, 3, 4);
console.log(result2);

4）与 webpack 集成

webpack.config.js

// 1.引入插件
const ESLintWebpackPlugin = require("eslint-webpack-plugin");

// 2.添加插件到 webpack 中
plugins: [
  new ESLintWebpackPlugin({
    // 指定检查文件的根目录
    context: path.resolve(__dirname, "src"),
  }),
],

5）运行指令

npx webpack

在控制台查看 Eslint 检查效果。

二、与 VSCode 集成

添加的 Eslint 只有在打包才会显示错误，可以让其在编写代码的时候就显示错误吗？

VSCode Eslint 插件

打开 VSCode，安装 Eslint 插件，即可不用编译就能看到错误，可以提前解决。

但是此时就会对项目所有文件默认进行 Eslint 检查了，dist 目录下的打包后文件就会报错。但是我们只需要检查 src 下面的文件，不需要检查 dist 下面的文件。

所以可以使用 Eslint 忽略文件解决。在项目根目录新建下面文件：.eslintignore

# 忽略dist目录下所有文件
dist