ESLint 从原理到实践：JavaScript/TypeScript 代码规范指南

流程图：ESLint 配置解析与合并

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

1. 初始化
2. 递归加载所有 extends 配置
3. 加载 plugins 中定义的规则和环境
4. 使用 rules 字段覆盖或新增规则
5. 为匹配 overrides.files 的文件生成文件级特定配置

核心要点：

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

4. 运行与忽略

# 检查 src 目录下所有文件
npx eslint src/
# 自动修复可修复的问题
npx eslint src/ --fix
# 指定配置文件
npx eslint src/ -c .eslintrc.js

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

node_modules/
dist/
*.min.js
public/

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

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

1. 使用共享配置

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

# 使用社区成熟的配置，如 Airbnb
npm install --save-dev eslint-config-airbnb-base eslint-plugin-import

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

2. 完美集成 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 无法做到的。

3. 与 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 的错误报告
  },
};

4. 性能优化

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

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

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

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

npx eslint src/ --cache

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

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

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

1. 编辑器集成

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

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

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

2. 构建工具集成

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

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