ESLint 实战指南：从原理到 TypeScript 工程化配置

ESLint 配置解析与合并

ESLint 在加载配置时，会遵循一个特定的合并顺序，理解这个顺序有助于排查配置冲突问题。

1. 初始化加载 .eslintrc.js
2. 递归加载所有 extends 配置
3. 生成基础配置对象
4. 加载 plugins 中定义的规则和环境
5. 生成中间配置
6. 使用 rules 字段覆盖或新增规则
7. 生成项目级最终配置
8. 为匹配 overrides.files 的文件生成文件级特定配置
9. 最终生效的配置

核心要点：

• extends 是基础，它提供了规则集合。
• plugins 是补充，它提供了新的规则'弹药库'，但默认不启用。
• rules 是微调，它决定哪些规则开启、关闭或改变警告级别。
• overrides 是特例，用于处理特殊情况，优先级最高。

运行与忽略

# 检查 src 目录下所有文件
npx eslint src/

# 自动修复可修复的问题
npx eslint src/ --fix

# 指定配置文件
npx eslint src/ -c .eslintrc.js

创建 .eslintignore 文件来忽略不需要检查的文件或目录，语法同 .gitignore。

node_modules/
dist/
*.min.js
public/

进阶之道：构建现代化前端工程规范

掌握了基础，我们来探索如何利用 ESLint 构建团队级别的、现代化的工程规范。

使用共享配置

为了保证团队内所有项目的代码风格统一，最佳实践是创建一个内部的共享配置包，例如 @my-company/eslint-config。

npm install --save-dev eslint-config-airbnb-base eslint-plugin-import

// .eslintrc.js
module.exports = {
  extends: ['airbnb-base'],
};

完美集成 TypeScript

为 TypeScript 项目配置 ESLint 需要额外的解析器和插件。

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

配置示例：

module.exports = {
  parser: '@typescript-eslint/parser', // 替换默认解析器
  plugins: ['@typescript-eslint'], // 加载插件
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended', // 使用插件推荐的规则集
  ],
  parserOptions: {
    project: './tsconfig.json', // 启用类型感知规则，更强大！
  },
};

类型感知规则 是 TypeScript ESLint 插件的一大亮点。通过指定 tsconfig.json，ESLint 能利用 TypeScript 的类型信息进行检查，例如检测未知的类型属性，这是纯 JavaScript Lint 无法做到的。

与 Prettier 和平共处

职责划分：

• ESLint：专注于代码质量，发现潜在错误和不良实践。
• Prettier：专注于代码格式，如缩进、空格、分号等。

为了避免两者冲突，我们需要 eslint-config-prettier 和 eslint-plugin-prettier。

npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier

配置（extends 顺序很重要）：

module.exports = {
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'prettier', // 必须放在最后，它会关闭所有与 Prettier 冲突的 ESLint 规则
  ],
  plugins: ['prettier'],
  rules: {
    'prettier/prettier': 'error', // 将 Prettier 的格式化结果作为 ESLint 的错误报告
  },
};

性能优化

对于大型项目，ESLint 的运行速度可能会成为瓶颈。

限制警告数量：在 CI 环境中，你可能不希望因为过多的 warn 阻止构建，但又想了解警告情况。

npx eslint src/ --max-warnings 10
# 当警告超过 10 个时，构建失败

缓存：ESLint 可以缓存检查结果，只对改动过的文件进行检查。

npx eslint src/ --cache

缓存文件默认存储在 .eslintcache 中，记得将其加入 .gitignore。

生态集成：无缝融入开发工作流

ESLint 的威力在于它能深度集成到你日常工作的每一个环节。

编辑器集成

以 VS Code 为例，安装 ESLint 扩展。

在 settings.json 中配置，实现保存时自动修复：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit" // 显式地在保存时执行 ESLint 的 auto-fix
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue" // 如果你使用 Vue
  ]
}

构建工具集成

• Webpack: 使用 eslint-webpack-plugin，在构建时进行检查。
• Vite: 使用 vite-plugin-eslint，在开发服务器启动时运行。

CI/CD 集成

这是保证代码质量的最后一道防线。在 CI 流程中加入 ESLint 检查，可以确保不符合规范的代码无法合并到主分支。

以 GitHub Actions 为例：

name: Lint Code
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run ESLint
        run: npx eslint . --ext .js,.ts,.jsx,.tsx # --max-warnings 0 (可选)

总结与最佳实践

1. 本地优先：始终将 ESLint 作为项目依赖进行本地安装。
2. 职责分离：ESLint 管质量，Prettier 管格式，通过 eslint-config-prettier 协同工作。
3. 配置分层：利用 extends 继承成熟配置，用 rules 进行微调，用 overrides 处理特例。
4. 团队统一：创建公司或团队内部的共享配置包 (@company/eslint-config)。
5. 即时反馈：配置好编辑器插件，在编码阶段就获得提示和修复。
6. 质量门禁：在 CI/CD 流程中加入 ESLint 检查，作为代码合并的强制条件。
7. 拥抱性能：在大型项目中使用 --cache 选项加速检查。

ESLint 是一个强大且高度可定制的工具。通过深入理解其原理并结合实践，你完全可以为你的团队打造一套高效、智能、自动化的代码质量保障体系。