前言

在现代前端开发中，代码质量和一致性是项目成功的关键因素。ESLint 作为 JavaScript/TypeScript 代码检查工具，能够帮助开发者发现潜在问题、统一代码风格。@antfu/eslint-config 是由 Anthony Fu 维护的一套开箱即用的 ESLint 配置，特别针对 Vue 3、TypeScript 和现代 JavaScript 项目进行了优化。

本文档基于实际项目经验，详细介绍了如何在 Vue3 + TypeScript + Vite 项目中正确配置和使用 @antfu/eslint-config，并记录了常见问题的解决方案。

目的

本文档旨在帮助开发者：

  • 快速在 Vue3 项目中集成 @antfu/eslint-config
  • 理解配置选项的含义和作用
  • 解决常见的解析错误和配置问题
  • 掌握最佳实践和注意事项

配置

1. 安装依赖

首先，确保你的项目已经安装了必要的依赖：

1
pnpm add -D @antfu/eslint-config eslint

或者使用 npm/yarn：

1
2
3
npm install -D @antfu/eslint-config eslint
# 或
yarn add -D @antfu/eslint-config eslint

2. 创建配置文件

在项目根目录创建 eslint.config.mjs 文件（注意：必须使用 .mjs 扩展名，因为 ESLint 9.x 使用扁平配置格式，且需要 ES 模块语法）。

重要提示：即使 package.json 中设置了 "type": "module"，ESLint 仍需要明确的 .mjs 扩展名来正确解析 ES 模块语法。

3. 基础配置示例

1
2
3
4
5
6
7
8
9
10
11
12
// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu({
  vue: true,        // 启用 Vue 3 支持
  typescript: true, // 启用 TypeScript 支持（重要！）
  
  rules: {
    // 自定义规则配置
    xxx
  },
})

4. 配置选项说明

核心选项

  • vue: true：启用 Vue 3 文件支持，自动配置 Vue 相关的 ESLint 规则
  • typescript: true：启用 TypeScript 支持，这是处理 TypeScript 语法的关键配置

5. package.json 脚本配置

在 package.json 中添加 lint 脚本：

1
2
3
4
5
6
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

遇到的问题

问题 1：配置文件解析错误

错误信息：

1
Parsing error: Unexpected token

问题描述：

  • 使用 .js 扩展名创建配置文件时，ESLint 无法正确解析 ES 模块语法（import/export）
  • 即使 package.json 中设置了 "type": "module"，某些工具仍需要明确的 .mjs 扩展名

解决方案：
将配置文件重命名为 eslint.config.mjs，确保使用 .mjs 扩展名。

问题 2：TypeScript 嵌套泛型解析错误

错误信息：

1
Parsing error: Unexpected token >>

问题代码示例：

1
const allUsersMap = ref<Map<number, UserInfo>>(new Map());

问题描述：

  • 当配置中只启用了 vue: true 而没有启用 typescript: true 时
  • ESLint 无法正确解析嵌套泛型语法（如 ref<Map<number, UserInfo>>）
  • >> 被误解析为 JavaScript 的右移运算符，而不是泛型闭合符号

根本原因：

  • 没有显式启用 TypeScript 支持时，TypeScript 解析器可能无法正确处理复杂的泛型语法
  • 这与 GitHub Issue #578 中描述的问题类似：当文件被添加到 ignoresTypeAware 时，会回退到普通 JavaScript 解析器，无法理解 TypeScript 语法

解决方案

解决方案 1：配置文件扩展名问题

步骤：

  1. 删除 eslint.config.js（如果存在）
  2. 创建 eslint.config.mjs 文件
  3. 使用 ES 模块语法编写配置

完整示例：

1
2
3
4
5
6
7
// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu({
  vue: true,
  typescript: true,
})

解决方案 2：TypeScript 解析错误

关键步骤：在配置中显式启用 TypeScript 支持

1
2
3
4
5
6
7
8
9
10
11
// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu({
  vue: true,
  typescript: true,  // ⚠️ 必须显式启用！
  
  rules: {
    // 自定义规则
  },
})

为什么需要显式启用？

  1. 默认行为不确定：虽然 @antfu/eslint-config 可能在某些情况下自动检测 TypeScript，但在处理复杂语法（如嵌套泛型）时可能失效
  2. Vue 文件特殊性：Vue 单文件组件（.vue）中的 <script setup> 使用 TypeScript 时，需要明确的配置来启用 TypeScript 解析器
  3. 避免解析器回退：显式配置确保文件不会被错误地使用 JavaScript 解析器处理

解决方案 3：完整的推荐配置

基于实际项目经验，推荐以下配置：

1
2
3
4
5
6
7
8
9
10
11
12
// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu({
  // 核心功能
  vue: true,
  typescript: true,
  
  // 自定义规则
  rules: {
  },
})

总结

关键要点

  1. 文件扩展名很重要：必须使用 eslint.config.mjs 而不是 .js，确保 ESLint 能正确解析 ES 模块语法

  2. 显式启用 TypeScript：即使项目使用 TypeScript，也要在配置中显式设置 typescript: true，特别是处理复杂泛型语法时

  3. 理解解析器机制：当 TypeScript 解析器未正确启用时，文件可能回退到 JavaScript 解析器，导致无法理解 TypeScript 语法

  4. 遵循最佳实践：

    • 始终同时启用 vue: true 和 typescript: true
    • 根据项目需求自定义规则
    • 定期更新 @antfu/eslint-config 到最新版本

常见错误对照表

错误信息 可能原因 解决方案
Parsing error: Unexpected token 配置文件扩展名错误 使用 .mjs 扩展名
Parsing error: Unexpected token >> 未启用 TypeScript 支持 添加 typescript: true
Parsing error: Unexpected token : 文件被添加到 ignoresTypeAware 移除相关配置或显式添加到 filesTypeAware

参考资源