ESLint 使用详解

ESLint 是一个用于识别和报告 JavaScript/TypeScript 代码中模式问题的强大工具，它能帮助开发者保持代码风格的一致性和避免潜在错误。

核心概念

• 规则 (Rules)：ESLint 的核心，每条规则代表一个代码检查点。例如 semi 强制分号的使用，quotes 强制引号的类型。
• 配置文件：告诉 ESLint 如何检查你的项目，包括使用哪些规则、什么错误级别等。
• 扩展 (Extend)：可以直接继承流行的、开源的配置方案，无需从零开始配置。
• 插件 (Plugins)：为 ESLint 提供额外的规则，用于检查特定框架（如 Vue, React）或库的代码。
• 解析器 (Parser)：ESLint 默认使用 Espree 解析器来理解 JavaScript。如果要检查 TypeScript 或其他语法，需要更换解析器（如 @typescript-eslint/parser）。

使用步骤

安装 ESLint

你可以选择本地安装（推荐，每个项目独立）或全局安装。

本地安装（最常用）：

# 在你的项目根目录下运行
npm init -y                    # 如果还没有 package.json，先初始化
npm install eslint --save-dev

# 或者使用 yarn
yarn add eslint --dev

全局安装（不推荐用于项目）：

npm install -g eslint

初始化配置

运行以下命令来生成你的第一个 ESLint 配置文件 (.eslintrc.*)。

# 如果你本地安装，使用 npx
npx eslint --init

# 如果你全局安装，直接运行
eslint --init

这会启动一个交互式命令行向导，问你几个问题：

1. How would you like to use ESLint?
   • To check syntax only (仅检查语法)
   • To check syntax and find problems (检查语法并发现问题) - 常用
   • To check syntax, find problems, and enforce code style (检查语法、发现问题并强制代码风格) - 最严格
2. What type of modules does your project use?
   • JavaScript modules (import/export) (ESM) - 现代项目常用
   • CommonJS (require/exports) (CJS)
3. Which framework does your project use?
   • React
   • Vue.js
   • None of these
4. Does your project use TypeScript? Yes / No
5. Where does your code run?
   • Browser (浏览器)
   • Node (Node.js) - 可以多选
6. How would you like to define a style for your project?
   • Use a popular style guide (使用流行风格指南，如 Airbnb, Standard)
   • Answer questions about your style (通过回答问题定义风格)
   • Inspect your JavaScript file(s) (根据现有文件推断风格)
7. Which style guide do you want to follow?
   • Airbnb (非常严格且流行)
   • Standard (相对宽松，自带规则)
   • Google
8. What format do you want your config file to be in?
   • JavaScript (.eslintrc.js) - 功能最强，可加注释
   • YAML (.eslintrc.yaml)
   • JSON (.eslintrc.json) - 也很常见

回答完所有问题后，ESLint 会自动安装所需的依赖并生成配置文件。

理解配置文件 (以 .eslintrc.js 为例)

初始化后，你会得到一个类似这样的文件：

module.exports = {
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": [
    "eslint:recommended", // 继承 ESLint 官方推荐规则
    "airbnb-base"        // 如果选择了 Airbnb，则会继承它的规则
  ],
  "parserOptions": {
    "ecmaVersion": "latest", // 使用最新的 ECMAScript 标准
    "sourceType": "module"   // 使用 ESM 模块
  },
  "rules": {
    // 在这里可以覆盖或添加自定义规则
    // "规则名": [错误级别, 选项]
    "semi": ["error", "always"], // 总是需要分号，否则报错
    "quotes": ["warn", "single"], // 推荐使用单引号，否则警告
    "no-console": "off" // 关闭 console 警告（覆盖继承的规则）
  }
};

错误级别：

• "off" 或 0 - 关闭规则
• "warn" 或 1 - 违反规则时显示警告（黄色，不影响退出码）
• "error" 或 2 - 违反规则时报错（红色，退出码为 1）

运行 ESLint 进行检查

配置好后，你就可以用它来检查代码了。

检查单个文件或多个文件：

npx eslint yourfile.js
npx eslint src/*.js
npx eslint src/**/*.js # 递归检查 src 目录下所有 js 文件

检查并自动修复问题：

许多规则（尤其是代码风格相关的）支持自动修复。

npx eslint yourfile.js --fix

集成到编辑器和构建流程中

• 编辑器集成：安装 ESLint 插件（如 VS Code 的 ESLint 扩展），这样你写代码时就能实时看到错误和下划线提示，无需运行命令。
• Git Hooks：使用 husky 和 lint-staged 在 git commit 前自动检查暂存区的文件，确保提交的代码符合规范。
• CI/CD 集成：在持续集成/部署流程（如 GitHub Actions, GitLab CI）中加入 eslint 检查步骤，如果代码有问题则阻止构建或部署。

进阶配置示例

配置 TypeScript

1. 安装必要的包：

   npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

2. 修改 .eslintrc.js：

   module.exports = {
     env: { ... },
     parser: '@typescript-eslint/parser', // 更换解析器
     extends: [
       'eslint:recommended',
       'plugin:@typescript-eslint/recommended' // 使用 TS 插件的推荐规则
     ],
     plugins: [
       '@typescript-eslint' // 启用 TS 插件
     ],
     rules: { ... },
     // 告诉 ESLint 如何处理 .ts 文件
     overrides: [
       {
         files: ['**/*.ts'],
         parser: '@typescript-eslint/parser',
       }
     ]
   };

配置 React

1. 安装必要的包（如果 eslint --init 时没自动安装）：

   npm install --save-dev eslint-plugin-react

2. 修改 .eslintrc.js：

   module.exports = {
     env: { ... },
     extends: [
       'eslint:recommended',
       'plugin:react/recommended', // React 推荐规则
       'plugin:react/jsx-runtime' // 适用于 React 17+ 的新 JSX 转换
     ],
     plugins: [
       'react'
     ],
     rules: { ... },
     settings: {
       react: {
         version: 'detect' // 自动检测 React 版本
       }
     }
   };

常用命令总结

命令	描述
npx eslint --init	初始化配置
npx eslint file.js	检查指定文件
npx eslint dir/**/*.js	递归检查目录下所有 JS 文件
npx eslint . --ext .js,.ts	检查当前目录下所有 .js 和 .ts 文件
npx eslint . --fix	检查并自动修复所有可修复的问题
npx eslint . --format codeframe	使用更清晰的代码帧格式输出结果