1、认识 ESLint

• 官网：https://eslint.org/
• 中文网：https://eslint.nodejs.cn/

ESLint 是一个高度可配置的 JavaScript 代码检查工具（linter），用于识别和报告 ECMAScript/JavaScript 代码中的问题模式。其核心目标是提升代码一致性、避免潜在错误，并确保遵循最佳实践。

✨ 核心特性：

• 问题检测：从潜在运行时错误到代码风格问题全面覆盖
• 完全插件化：每条规则都是独立插件，支持运行时扩展
• 生态丰富：支持社区插件、自定义配置和解析器扩展

📋 系统要求：需要安装 Node.js（^20.19.0、22.13.0 或 ≥24）并支持 SSL（官方 Node.js 发行版已内置）

2、使用指南 🚀

2.1、安装 ESLint 插件

npm i -D eslint globals @eslint/js

2.2、安装 VS Code 插件

• ESLint
  • 使用dbaeumer.vscode-eslint在插件市场搜索安装

2.3、配置 npm 脚本

"lint": "eslint src --fix"

📝 注：src 为待检查目录，可省略。执行 npm run lint 即可进行检查和自动修复

使用命令npm run lint对项目文件进行检查并修复

3、配置清单 ⚙️

3.1、配置文件

💡 推荐使用扁平配置文件（eslintrc 格式已弃用）

此处仅列举个人喜好的方式配置 ESLint：

• eslint.config.js（推荐）
• eslint.config.mjs
• eslint.config.cjs

它应该放在项目的根目录下，并导出一个配置对象的数组

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

export default defineConfig([
  {
    rules: {
      semi: "error",
      "prefer-const": "error",
    },
  },
]);

⚠️ 注意：若 package.json 未指定 "type": "module"，需使用 CommonJS 格式（module.exports）

TypeScript 配置支持：

• Deno/Bun：原生支持
• Node.js：需安装 jiti 依赖（npm install -D jiti）
• 支持扩展名：.ts、.mts、.cts

3.2、配置对象

每个配置对象都包含 ESLint 需要在一组文件上执行的所有信息。每个配置对象都由以下属性组成：

• name: 配置对象的名称
• basePath: 应用到的子目录路径
• files: 应用于的文件的通配符模式数组
• ignores: 忽略文件的通配符模式数组
• extends: 要应用的其他配置的字符串、配置对象或配置数组的数组
• languageOptions: 包含与如何为代码检查配置 JavaScript 相关的设置的对象
  • ecmaVersion: 支持的 ECMAScript 版本，默认：latest
  • sourceType: JavaScript 源代码的类型，可选值：script、module、commonjs，默认：module
  • globals: 添加到全局作用域的其他对象
  • parser: 包含 parse() 方法或 parseForESLint() 方法的对象
  • parserOptions: 可用选项取决于解析器
• linterOptions: 包含与代码检查过程相关的设置的对象
  • noInlineConfig: 是否允许内联配置
  • reportUnusedDisableDirectives: 是否以及如何应跟踪和报告未使用的禁用和启用指令
  • reportUnusedInlineConfigs: 是否以及如何跟踪和报告未使用的内联配置，默认：off
• processor: 包含 preprocess() 和 postprocess() 方法的对象或指示插件内处理器名称的字符串
• plugins: 插件
• rules: 配置规则
• settings: 设置

---

拓展: 全局忽略

使用 globalIgnores() 辅助函数来指定要忽略的文件模式

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

export default defineConfig([globalIgnores([".config/*"])]);

4、推荐配置 🎯

更多规则: https://eslint.nodejs.cn/docs/latest/rules/

4.1、基础 JavaScript

import js from "@eslint/js";
import globals from "globals";
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
  globalIgnores(["**/*.config.{js,mjs,cjs,ts,mts,cts}"]),
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts,vue}"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: {
      globals: globals.browser,
    }
  },
  {
    plugins: {},
    rules: {
      // 禁止使用 var 声明变量，使用 var 会触发错误
      'no-var': 'error',
      // 关闭禁止使用异步 Promise 执行器的规则
      'no-async-promise-executor': 'off',
      // 关闭禁止使用未定义变量的规则
      'no-undef': 'off',
    }
  }
]);

4.2、基础 TypeScript

安装typescript-eslint插件

npm i -D typescript-eslint

配置文件

import js from "@eslint/js";
import globals from "globals";
import tseslint from "typescript-eslint";
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
  globalIgnores(["**/*.config.{js,mjs,cjs,ts,mts,cts}"]),
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts,vue}"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: {
      globals: globals.browser,
    }
  },
  tseslint.configs.recommended,
  {
    plugins: {},
    rules: {
      // 禁止使用 var 声明变量，使用 var 会触发错误
      'no-var': 'error',
      // 要求类型定义统一使用 interface，违反此规则会触发错误
      '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
      // 关闭禁止使用显式 any 类型的规则
      '@typescript-eslint/no-explicit-any': 'off',
      // 关闭禁止使用异步 Promise 执行器的规则
      'no-async-promise-executor': 'off',
      // 关闭禁止使用未定义变量的规则
      'no-undef': 'off',
    }
  }
]);

4.3、TypeScript + Vue

安装typescript-eslint和eslint-plugin-vue插件

npm i -D typescript-eslint eslint-plugin-vue

配置文件

import js from "@eslint/js";
import globals from "globals";
import tseslint from "typescript-eslint";
import pluginVue from "eslint-plugin-vue";
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
  globalIgnores(["**/*.config.{js,mjs,cjs,ts,mts,cts}"]),
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts,vue}"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: {
      globals: globals.browser,
    }
  },
  tseslint.configs.recommended,
  pluginVue.configs["flat/essential"],
  {
    files: ["**/*.vue"],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser
      }
    }
  },
  {
    plugins: {},
    rules: {
      // 禁止使用 var 声明变量，使用 var 会触发错误
      'no-var': 'error',
      // 要求类型定义统一使用 interface，违反此规则会触发错误
      '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
      // 关闭禁止使用显式 any 类型的规则
      '@typescript-eslint/no-explicit-any': 'off',
      // 关闭 Vue 组件名必须为多单词的规则
      'vue/multi-word-component-names': 'off',
      // 关闭禁止使用异步 Promise 执行器的规则
      'no-async-promise-executor': 'off',
      // 关闭禁止使用未定义变量的规则
      'no-undef': 'off',
    }
  }
]);

5、总结 📋

ESLint 提供了完整的 JavaScript/TypeScript 代码质量保障方案，通过灵活的配置体系和丰富的插件生态，能够适应各种项目需求。建议根据项目技术栈选择合适的配置方案，并定期更新规则以保持代码质量的最佳状态。

🔗 更多规则参考：https://eslint.nodejs.cn/docs/latest/rules/