前端工程化工具系列（一）—— ESLint(v9.4.0)：代码质量守护者 基础篇
ESLint 作为前端工程化中的重要工具，主要用于检查和修复 JavaScript/TypeScript 代码中的错误。目的是为了统一代码风格，并确保代码的一致性和可维护性。
1. 环境要求
v9 以上的 ESLint，支持 v18.18.0+，v20.9.0+ 以及 v21.1.0+ 的 Node.js，不支持 v19 及之前的版本。
在命令行中输入以下内容来查看当前系统中已安装的 node 版本。
node -v
Node.js 推荐使用 v18.20.3+ 或者 v20.13.1+。
包管理器推荐使用 PNPM(v9.2.0)，而不是 NPM 或者 Yarn。详细的原因和使用方式见《前端工程化工具系列（七）—— PNPM(v9.2.0)：高性能的 NPM 替代品》
2. 安装
这里以使用 ESLint + Airbnb 风格为例。
2.1 安装 ESLint
在对应的项目下打开命令行工具（如：Windows 中的 cmd.exe、PowerShell，MacOS 中的 Bash、Zsh），输入以下内容后回车：
pnpm install -D eslint @eslint/js
如果使用 NPM 或者 Yarn 作为包管理器，直接将上方内容中的 pnpm 替换成对应的包管理器名即可，例：npm install -D eslint @eslint/js
2.2 针对 JavaScript
安装对应的 Airbnb 配置和插件。
pnpm install -D eslint-config-airbnb-base eslint-plugin-import
- eslint-config-airbnb-base
包含了airbnb 最基础（不包含 React 相关）的JS编码风格规则。
- eslint-plugin-import
模块导入识别
2.3 针对 TypeScript
在 JavaScript 的基础上多了规则、插件和解析器。
pnpm install -D eslint-config-airbnb-typescript typescript-eslint
- eslint-config-airbnb-typescript
Airbnb 风格的 TypeScript 支持。它将一些常见配置都加了进去，省下了好多工作量。
该插件包含了@typescript-eslint/parser（TypeScript 解析器），它调用 @typescript-eslint/typescript-estree（通过在给定的源代码上调用 TypeScript 编译器，就是 npm i typescript -D 安装的那个，以产生 TypeScript AST，然后将该 AST 转换为 ESLint 期望的格式）。ESlint 默认的解析器叫 espree。
这是一个匈牙利布达佩斯技术和经济大学的学生做的，想想自己的大学生活都在做啥…
- typescript-eslint
针对 TypeScript 运行分析规则，用于替代之前的 @typescript-eslint/eslint-plugin 与 @typescript-eslint/parser 。
2.4 兼容之前的配置
从 ESLint v9.0.0 开始，默认采用新的扁平化配置系统。绝大部份扩展和插件没有做适配，因此需要通过以下官方包来兼容旧的配置。
pnpm install -D @eslint/compat @eslint/eslintrc
2.5 支持 Vue
pnpm add -D vue-eslint-parser eslint-plugin-vue
3 配置
在项目的根目录下创建 ESLint 的配置文件：eslint.config.js。
3.1 针对 JavaScript
在 eslint.config.js 中加入以下配置：
/* eslint-disable no-underscore-dangle */ /* eslint-disable import/no-extraneous-dependencies */ // eslint-disable-next-line import/no-unresolved import { fixupConfigRules } from '@eslint/compat'; import { FlatCompat } from '@eslint/eslintrc'; import js from '@eslint/js'; import path from 'path'; import { fileURLToPath } from 'url'; // 模仿 CommonJS 变量 -- 如果使用 CommonJS 则不需要 const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const flatCompat = new FlatCompat({ baseDirectory: __dirname, // 可选；默认值： process.cwd() resolvePluginsRelativeTo: __dirname, // 可选 recommendedConfig: js.configs.recommended, // 默认使用 "eslint:recommended" }); export default [{ // 配置需要被忽略的文件，替代之前的 .eslintignore 文件 ignores: [ '.idea', '.vscode', '**/dist/', ], },{ // eslint-plugin-import 目前还没有兼容 flat，因此增加以下配置 languageOptions: { parserOptions: { // Eslint doesn't supply ecmaVersion in `parser.js` `context.parserOptions` // This is required to avoid ecmaVersion正像注释中所说 eslint-plugin-import 尚未支持 flat config，因此添加了一些配置，以后支持了会更新。
3.2 针对 TypeScript
/* eslint-disable @typescript-eslint/no-unsafe-member-access */ /* eslint-disable @typescript-eslint/naming-convention */ /* eslint-disable @typescript-eslint/no-unsafe-call */ /* eslint-disable @typescript-eslint/no-unsafe-assignment */ /* eslint-disable no-underscore-dangle */ /* eslint-disable import/no-extraneous-dependencies */ // eslint-disable-next-line import/no-unresolved import { fixupConfigRules } from '@eslint/compat'; import { FlatCompat } from '@eslint/eslintrc'; import js from '@eslint/js'; import path from 'path'; import { fileURLToPath } from 'url'; // mimic CommonJS variables -- not needed if using CommonJS const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const flatCompat = new FlatCompat({ baseDirectory: __dirname, // optional; default: process.cwd() resolvePluginsRelativeTo: __dirname, // optional recommendedConfig: js.configs.recommended, // optional unless you're using "eslint:recommended" }); export default [{ // 配置需要被忽略的文件，替代之前的 .eslintignore 文件 ignores: [ '.idea', '.vscode', '**/dist/', ], },{ // eslint-plugin-import 目前还没有兼容 flat，因此增加以下配置 languageOptions: { parserOptions: { // Eslint doesn't supply ecmaVersion in `parser.js` `context.parserOptions` // This is required to avoid ecmaVersion3.3 支持 Vue
...fixupConfigRules( // 因为v9变化较大，为了兼容之前的 config，官方提供了转换整个旧的 config 的方法 flatCompat.config({ extends: [ 'airbnb-base', 'airbnb-typescript/base', 'plugin:vue/vue3-essential', // 增加这行 'plugin:@typescript-eslint/eslint-recommended', 'plugin:@typescript-eslint/recommended', ], parser: 'vue-eslint-parser', // 增加这行 parserOptions: { parser: '@typescript-eslint/parser', project: './tsconfig.json', extraFileExtensions: ['.vue'], // 在这里添加.vue文件扩展名 },4 结合 Husky
利用 Husky 在 git commit 时自动校验文件中的代码内容，如不符合规范，则不能被 commit。详细操作见《前端工程化工具系列（五）》中的 2.1节。
5 结合 VSCode
配合 VSCode 插件，可在做文件保存时自动修复错误。详细操作见《前端工程化工具系列（六）—— VS Code(v1.89.1)：强大的代码编辑器》。
6 问题解决
问题1：
Error: Could not find config file.
解决：
ESLint9 的配置文件名必须为 eslint.config.js，之前的 eslintrc.(可为 空，js, yaml, yml, json）都被废弃了。
问题2：
SyntaxError: Cannot use import statement outside a module
解决：
两种方式：
- 在 package.json 中添加 “type”: “module”，形如：
{ "type": "module", "devDependencies": { "@eslint/js": "^9.4.0", "eslint": "^9.4.0", "eslint-config-airbnb-base": "^15.0.0", "eslint-plugin-import": "^2.29.1" } }- 将配置内容修改为 CommonJS 格式：
// eslint.config.js module.exports = [ { rules: { semi: "error", "prefer-const": "error" } } ];问题3:
.eslintignore 中定义的忽略文件不起作用。
解决：
ESLint9 中需要在 eslint.config.js 中进行配置，如：
{ ignores: [ '/dist', '.idea', '.vscode', ], },node_modules 和 .git 这两个文件夹会默认被添加进来，因此不需要专门配置。
问题4:
Unable to resolve signature of class decorator when called as an expression.
需要在 tsconfig.json 中的 compilerOptions 节点下添加：
"experimentalDecorators": true
问题5:
TypeError: context.getAncestors is not a function.
如上文提到的，有些旧的配置在转换成 flat config 时会有错误，需要通过安装和配置以下内容来解决：
pnpm add @eslint/compat -D
import { fixupConfigRules } from '@eslint/compat'; ...fixupConfigRules(flatCompat(旧的配置))详情请参看以上的 3 配置。
问题6:
TypeError: Key “rules”: Key “import/extensions”: Could not find plugin “import”.
需要在 eslint.config.js 中增加配置：
pnpm add eslint-plugin-import -D
import eslintImport from 'eslint-plugin-import'; plugins: { import: eslintImport, // 添加了 airbnb-base 就不用再加这个了 },详情请参看以上的 3.2 针对 TypeScript，被注释掉的部分。
问题7:
Unable to resolve path to module ‘typescript-eslint’.eslintimport/no-unresolved.
需要在 eslint.config.js 中增加配置：
settings: { 'import/resolver': { typescript: {}, }, },详情请参看以上的 3.2 针对 TypeScript。
- typescript-eslint
- eslint-config-airbnb-typescript
