ESLint 常用命令

ESLint 是 JavaScript/TypeScript 的代码检查工具，用于发现代码问题并强制统一代码风格。

⚠️ ESLint 9+ 推荐使用 flat config 格式（eslint.config.js），旧版 .eslintrc 配置将在未来版本移除。详见迁移指南。

环境要求

Node.js：^20.19.0、^22.13.0 或 >=24
TypeScript：5.3 或更高版本（如需使用类型定义）

安装

bash

# 安装 ESLint（-D 是 --save-dev 的简写，表示只在开发环境使用）
npm install -D eslint

# 安装 TypeScript 支持（如果项目使用 TypeScript）
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

# 安装 Vue 支持（如果项目使用 Vue）
npm install -D eslint-plugin-vue

初始化配置

bash

# 交互式问答（推荐新手）
npm init @eslint/config@latest

# 或使用 npx
npx eslint --init

常用命令

检查代码

bash

# 检查指定文件
npx eslint src/index.ts

# 检查整个目录
npx eslint src/

# 检查当前目录下所有文件
npx eslint .

bash

# ESLint 8 及以下：指定文件扩展名
# --ext 指定要检查的文件类型
npx eslint src/ --ext .js,.ts,.vue

⚠️ --ext 在 ESLint 9+ 的 flat config 中不再需要，文件类型通过配置文件中的 files 字段指定。但在旧版 .eslintrc 配置中仍然有效。

自动修复

bash

# 自动修复可修复的问题
# --fix 表示自动修复，ESLint 会尝试修复所有能修复的问题
npx eslint --fix src/

# 修复指定文件
npx eslint --fix src/index.ts

缓存（加速重复检查）

bash

# 使用缓存（只检查变更的文件，提升检查速度）
# --cache 表示启用缓存，只检查修改过的文件
npx eslint --cache src/

# 缓存文件默认在 node_modules/.cache/eslintcache
# 建议加入 .gitignore
echo ".eslintcache" >> .gitignore

忽略文件

bash

# ESLint 9+（flat config）：在 eslint.config.js 中配置 ignores
# 忽略的文件不会被 ESLint 检查
export default [
  {
    ignores: [
      'node_modules/**',    # 忽略依赖目录
      'dist/**',            # 忽略构建产物
      '*.min.js',           # 忽略压缩文件
      'coverage/**',        # 忽略测试覆盖率报告
    ],
  },
]

bash

# ESLint 8 及以下：使用 .eslintignore 文件（类似 .gitignore 语法）
node_modules/
dist/
*.min.js

# 或在 package.json 中配置（ESLint 9+ 已废弃此方式）
{
  "eslintIgnore": ["node_modules", "dist"]
}

⚠️ ESLint 9+（flat config）已废弃 .eslintignore 文件和 package.json 中的 eslintIgnore 字段，请使用配置文件中的 ignores 字段。

配置文件

eslint.config.js（新格式，ESLint 9+）

import js from '@eslint/js'

export default [
  js.configs.recommended,    // 使用 ESLint 推荐规则
  {
    rules: {
      'no-unused-vars': 'warn',    // 未使用的变量：警告（避免声明了但没用的变量）
      'no-console': 'warn',        // console 语句：警告（生产环境不应有 console）
    },
  },
]

.eslintrc.js（旧格式）

Vue 项目需要额外安装配置包：

bash

npm install -D eslint-plugin-vue @vue/eslint-config-typescript @vue/eslint-config-prettier

module.exports = {
  env: {
    browser: true,      // 浏览器环境（可使用 window、document 等全局变量）
    node: true,         // Node.js 环境（可使用 process、__dirname 等全局变量）
    es2021: true,       // ES2021 语法支持
  },
  extends: [
    'eslint:recommended',           // ESLint 推荐规则
    'plugin:vue/vue3-recommended',  // Vue 3 推荐规则
    '@vue/eslint-config-typescript', // TypeScript 支持
  ],
  rules: {
    'no-unused-vars': 'warn',    // 未使用的变量：警告
    'no-console': 'warn',        // console 语句：警告
  },
}

常用规则说明

为什么要开启这些规则？

规则	说明	为什么开启
`no-unused-vars`	禁止未使用的变量	避免声明了但没用的变量，保持代码整洁
`no-console`	禁止 console 语句	生产环境不应有 console，避免泄露调试信息
`no-debugger`	禁止 debugger 语句	生产环境不应有 debugger，避免暂停代码执行
`no-alert`	禁止 alert 语句	alert 体验差，应使用更友好的提示方式
`no-var`	禁止使用 var	var 有变量提升问题，推荐使用 let/const
`prefer-const`	优先使用 const	不变的变量用 const，代码更清晰
`eqeqeq`	要求使用 ===	== 会进行类型转换，容易产生意外结果
`no-throw-literal`	禁止抛出字面量	throw 应抛出 Error 对象，便于调试
`no-implicit-globals`	禁止隐式全局变量	避免变量泄漏到全局作用域

规则严重级别

级别	值	说明
关闭	`0` 或 `'off'`	不检查这条规则
警告	`1` 或 `'warn'`	检查，但不报错（黄色提示）
错误	`2` 或 `'error'`	检查，且报错（红色提示，退出码非 0）

// 示例：配置规则
rules: {
  'no-console': 'warn',           // 警告
  'no-debugger': 'error',         // 错误
  'no-unused-vars': 'off',        // 关闭
}

与 Vue / Vite 项目集成

Vue 3 + TypeScript 项目配置

bash

# 安装依赖
npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-vue

ESLint 9+ 配置（推荐）

// eslint.config.js
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import vue from 'eslint-plugin-vue'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  ...vue.configs['flat/recommended'],
  {
    files: ['*.vue', '**/*.vue'],    // 只检查 Vue 文件
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser,     // Vue 文件中使用 TypeScript 解析器
      },
    },
    rules: {
      'no-unused-vars': 'warn',
      'no-console': 'warn',
      'vue/multi-word-component-names': 'off',  // 允许单词组件名
    },
  },
]

ESLint 8 配置（旧格式）

// .eslintrc.js
module.exports = {
  root: true,
  env: {
    browser: true,
    node: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    '@vue/eslint-config-typescript',
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    'no-unused-vars': 'warn',
    'no-console': 'warn',
    'vue/multi-word-component-names': 'off',  // 允许单词组件名
  },
}

在 package.json 中添加脚本

json

{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint --fix src/"
  }
}

常见问题

与 Prettier 冲突

bash

# 安装 eslint-config-prettier（禁用 ESLint 中与 Prettier 冲突的规则）
npm install -D eslint-config-prettier

ESLint 9+ flat config 配置

// eslint.config.js
import js from '@eslint/js'
import prettier from 'eslint-config-prettier'

export default [
  js.configs.recommended,
  prettier,  // 放在最后，覆盖前面的格式化规则
]

ESLint 8 旧格式配置

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    'prettier',  // 放在最后，覆盖前面的格式化规则
  ],
}

VSCode 保存时自动修复

安装 ESLint 扩展后，在项目根目录创建 .vscode/settings.json：

json

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue"
  ]
}

保存文件时会自动修复 ESLint 能修复的问题（如引号风格、分号等）。

💡 如果同时使用 Prettier，参考 Prettier 常用命令中的配合配置。

提交代码时自动修复（可选）

使用 lint-staged + husky 在 git commit 时自动检查，详见 husky + lint-staged 常用命令。

忽略某个文件或某行

// 忽略整个文件
/* eslint-disable */

// 忽略下一行
// eslint-disable-next-line no-console
console.log('debug')

// 忽略当前行
console.log('debug') // eslint-disable-line no-console

常见报错及解决方案

Parsing error: Unexpected token

bash

# 原因：ESLint 无法解析语法（如 TypeScript、JSX）
# 解决：安装对应的解析器

# TypeScript 项目
npm install -D @typescript-eslint/parser

# Vue 项目
npm install -D eslint-plugin-vue

Definition for rule 'xxx' was not found

bash

# 原因：规则名称拼写错误或未安装对应插件
# 解决：检查规则名称，安装对应插件

# 示例：vue 规则需要安装 eslint-plugin-vue
npm install -D eslint-plugin-vue

ESLint: Failed to load config

bash

# 原因：配置文件格式错误或依赖未安装
# 解决：检查配置文件语法，确保依赖已安装

# 重新安装依赖
rm -rf node_modules
npm install

临时使用旧版配置文件（ESLint 9+）

如果项目尚未迁移到 flat config，可通过环境变量临时使用旧版 .eslintrc 格式：

bash

# 命令行临时降级
ESLINT_USE_FLAT_CONFIG=false npx eslint src/

# package.json 中配置
cross-env ESLINT_USE_FLAT_CONFIG=false eslint src/

⚠️ 这只是过渡方案，建议尽快迁移到 eslint.config.js。

参考

CLI 常用参数

参数	说明	示例
`--fix`	自动修复可修复的问题	`npx eslint --fix src/`
`--cache`	启用缓存，只检查修改过的文件	`npx eslint --cache src/`
`--ext`	指定文件扩展名（flat config 中用 `files` 字段替代）	`npx eslint src/ --ext .js,.ts`
`--no-error-on-unmatched-pattern`	无匹配文件时不报错	`npx eslint --no-error-on-unmatched-pattern src/`
`--max-warnings`	超过指定警告数时报错（CI 有用）	`npx eslint --max-warnings 0 src/`
`--format`	指定输出格式	`npx eslint --format json src/`
`--ignore-path`	指定忽略文件路径（ESLint 9+ 已废弃）	`npx eslint --ignore-path .eslintignore src/`
`--debug`	输出调试信息	`npx eslint --debug src/`

与同类工具的区别

工具	定位	特点	适用场景
ESLint	代码检查 + 风格	规则丰富，生态强大，支持自动修复	JavaScript/TypeScript 项目首选
Prettier	代码格式化	有态度的格式化，配置少	纯格式化需求（缩进、引号、分号）
Biome	检查 + 格式化	Rust 实现，速度极快，ESLint + Prettier 替代品	新项目可考虑，生态较新
StandardJS	检查 + 格式化	零配置，开箱即用	不想花时间配置规则

💡 推荐组合：ESLint（代码检查）+ Prettier（代码格式化），各司其职，覆盖最全面。

ESLint 常用命令 ​

环境要求 ​

安装 ​

初始化配置 ​

常用命令 ​

检查代码 ​

自动修复 ​

缓存（加速重复检查） ​

忽略文件 ​

配置文件 ​

eslint.config.js（新格式，ESLint 9+） ​

.eslintrc.js（旧格式） ​

常用规则说明 ​

为什么要开启这些规则？ ​

规则严重级别 ​

与 Vue / Vite 项目集成 ​

Vue 3 + TypeScript 项目配置 ​

ESLint 9+ 配置（推荐） ​

ESLint 8 配置（旧格式） ​

在 package.json 中添加脚本 ​

常见问题 ​

与 Prettier 冲突 ​

ESLint 9+ flat config 配置 ​

ESLint 8 旧格式配置 ​

VSCode 保存时自动修复 ​

提交代码时自动修复（可选） ​

忽略某个文件或某行 ​

常见报错及解决方案 ​

Parsing error: Unexpected token ​

Definition for rule 'xxx' was not found ​

ESLint: Failed to load config ​

临时使用旧版配置文件（ESLint 9+） ​

参考 ​

CLI 常用参数 ​

与同类工具的区别 ​

ESLint 常用命令

环境要求

安装

初始化配置

常用命令

检查代码

自动修复

缓存（加速重复检查）

忽略文件

配置文件

eslint.config.js（新格式，ESLint 9+）

.eslintrc.js（旧格式）

常用规则说明

为什么要开启这些规则？

规则严重级别

与 Vue / Vite 项目集成

Vue 3 + TypeScript 项目配置

ESLint 9+ 配置（推荐）

ESLint 8 配置（旧格式）

在 package.json 中添加脚本

常见问题

与 Prettier 冲突

ESLint 9+ flat config 配置

ESLint 8 旧格式配置

VSCode 保存时自动修复

提交代码时自动修复（可选）

忽略某个文件或某行

常见报错及解决方案

Parsing error: Unexpected token

Definition for rule 'xxx' was not found

ESLint: Failed to load config

临时使用旧版配置文件（ESLint 9+）

参考

CLI 常用参数

与同类工具的区别