ESLint 9 在 Vue TypeScript 项目中采用 Flat 配置

问题陈述

随着 ESLint 9 的发布，原有的 .eslintrc 配置格式已被 Flat 配置格式所取代。对于使用 Vue 结合 TypeScript 的开发者来说，迁移到新格式时常遇到几个痛点：

1. 配置复杂性：需要同时配置 Vue 的模板验证和 TypeScript 的类型检查
2. 解析器冲突：需要协调 vue-eslint-parser 和 @typescript-eslint/parser
3. 规则兼容性：确保 Vue 规则、TypeScript 规则和 Prettier 格式化不冲突
4. 文件路径处理：设置正确的文件匹配模式和 TypeScript 项目引用

这些问题导致开发者难以充分利用 ESLint 9 的新特性，从而影响开发效率和代码质量。

解决方案

依赖安装

确保安装必要的软件包：

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

核心配置

以下是完整的 eslint.config.js 配置，支持 Vue 3 和 TypeScript：

// @ts-check
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import vueParser from 'vue-eslint-parser';
import pluginVue from 'eslint-plugin-vue';
import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  // 全局忽略配置
  {
    ignores: [
      '**/dist/**',
      '**/node_modules/**',
      '**/cypress/**',
      '**/coverage/**'
    ]
  },
  
  // 基础配置 (所有 JS/TS/VUE 文件)
  {
    files: ['**/*.{js,ts,vue}'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module'
    }
  },

  // ESLint 推荐规则
  eslint.configs.recommended,
  
  // TypeScript 配置
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: true // 自动查找最近的 tsconfig.json
      }
    }
  },
  
  // Vue TypeScript 集成
  ...pluginVue.configs['flat/recommended'],
  {
    files: ['**/*.vue'],
    languageOptions: {
      parser: vueParser,
      parserOptions: {
        parser: tseslint.parser, // 使用 TypeScript 解析器处理 <script> 块
        project: './tsconfig.app.json',
        extraFileExtensions: ['.vue'],
        sourceType: 'module'
      }
    },
    rules: {
      // 自定义 Vue 规则
      'vue/html-self-closing': ['error', {
        html: { void: 'always', normal: 'never', component: 'always' },
        svg: 'always',
        math: 'always'
      }],
      'vue/require-default-prop': 'off',
      'vue/singleline-html-element-content-newline': 'off'
    }
  },
  
  // Prettier 集成 (禁用冲突规则)
  eslintConfigPrettier
];

关键配置说明

1. 文件分段处理：分别为全局、JS/TS、Vue 文件定义不同配置
2. 双重解析器：vue-eslint-parser + typescript-eslint 无缝协作
3. 规则继承：只需使用 flat/recommended 包含所有 Vue 推荐规则
4. Prettier 后置：确保作为最后配置以覆盖所有冲突规则

TypeScript 配置 (tsconfig.json)

确保 TypeScript 识别 .vue 文件：

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"  // 包含 Vue 文件
  ]
}

编辑器配置 (VS Code)

在 .vscode/settings.json 中启用 Flat 配置：

{
  "eslint.experimental.useFlatConfig": true,
  "eslint.validate": [
    "javascript",
    "typescript",
    "vue"
  ]
}

常见问题解决

文件识别问题

如果遇到 .vue 文件不被识别的情况：

1. 检查 tsconfig.json 是否包含 "**/*.vue"
2. 确保添加 extraFileExtensions: ['.vue'] 到 ESLint 配置

{
  parserOptions: {
    project: './tsconfig.app.json',
    extraFileExtensions: ['.vue'], // 关键配置
    sourceType: 'module'
  }
}

规则优先级

当规则发生冲突时：

1. 将更具体的规则配置放在更靠后的位置
2. 使用 eslint-disable 暂时禁用特定文件的规则
3. 通过 rules 对象明确覆盖继承规则

rules: {
  '@typescript-eslint/no-explicit-any': 'warn', // 重写严格规则
  'vue/require-default-prop': 'off' // 禁用特定规则
}

性能优化建议

对于大型项目：

{
  parserOptions: {
    project: [
      './tsconfig.app.json',
      './tsconfig.vitest.json' // 分层配置提升性能
    ]
  }
}

最佳实践

1. 避免多重配置：不要同时使用 essential, recommended 等多套规则
2. 增量迁移：对于现有项目，分阶段添加规则集
3. 版本控制：锁定主要依赖版本，避免兼容问题

"devDependencies": {
  "eslint": "^9.0.0",
  "eslint-plugin-vue": "^9.25.0",
  "typescript-eslint": "^7.7.0"
}

4. 自动化集成：将 ESLint 整合到 CI/CD 流程

重要提醒

1. 确保所有团队成员使用相同版本的 ESLint 和插件
2. 定期更新依赖以获取安全补丁和性能改进
3. 复杂的自定义规则应添加清晰的注释说明原因

本配置为 ESLint 9、Vue 3 和 TypeScript 项目提供了开箱即用的基础解决方案，兼顾了代码质量检查和项目构建效率。当技术栈更新时，可在此基础上灵活调整配置。