Vue3项目里ESLint报错没完没了？怎么快速配置且不破坏开发节奏？

很多刚从Vue2转过来，或者第一次搭Vue3项目的朋友，都会遇到这个头疼的事：脚手架默认带的ESLint要么一写setup语法糖就飘红defineProps，要么和Prettier打架一会儿换引号一会儿换行，甚至改完自动修复还报另一个错，完全没法专心写业务，别急，这篇文章把Vue3 ESLint配置的核心逻辑、常见坑、快速生效方案全讲透，看完你能搞定80%的配置问题，剩下的20%查对应文档也能快速定位。

为什么Vue3的ESLint比Vue2“麻烦”？

先搞明白原因，配置起来才不会盲目试错，Vue3相比Vue2最大的变化，就是引入了<script setup>编译宏、Composition API，还有更严格的TypeScript支持趋势——这些Vue2里没有的东西，ESLint的默认规则或者旧插件根本识别不了,飘红是必然的。

举个最常见的例子：<script setup>里的defineProps、defineEmits、defineExpose、withDefaults这些，是Vue3编译器自动注入的变量，在JS/TS层面并没有显式声明导入，旧的ESLint Vue插件（比如eslint-plugin-vue@7.x之前的版本）或者普通的eslint:recommended规则，会直接把它们当成“未定义的变量”报错，还有Composition API里的ref、reactive这些，要是用了自动导入插件unplugin-auto-import，没配置好ESLint全局变量,也会飘红一片。

现在搭项目不管是Vite还是Vue CLI，默认都会推荐TypeScript，TS有自己的类型检查，ESLint也有类型相关的规则包，要是两者的规则冲突了（比如ESLint要求强制显式返回类型，但TS有隐式类型推断的优势），或者只开了TS没开配套的ESLint，也会觉得“规则乱糟糟”。

用什么工具搭Vue3 ESLint环境最快？

推荐优先用Vite + create-vue官方脚手架，别用老掉牙的Vue CLI了——create-vue已经把Vue3 ESLint的基础坑填了一半，生成的配置文件结构清晰,后续改起来也方便。

create-vue生成项目的时候，会有几个和ESLint相关的选项,一定要选对：

1. 第一个“Add TypeScript?”：根据项目需要选，选Yes的话后续会自动装@typescript-eslint相关包；
2. 第二个“Add JSX Support?”：没用到JSX（比如用Element Plus、Ant Design Vue这些纯Vue组件库）的话可以不选；
3. 第三个“Add Vue Router for SPA?”、第四个“Add Pinia for state management?”：选不选都行，和ESLint基础配置无关，但要是选了Pinia/Router,后续可能需要加对应的规则包；
4. 第五个“Add ESLint for code quality?”：必须选Yes,这是基础；
5. 第六个“Add Prettier for code formatting?”：建议选Yes，选了之后会自动帮你搭好ESLint和Prettier的兼容配置,不用自己手写一堆规则冲突的解决代码；
6. 后面的Cypress、Vitest这些测试工具,选不选都行。

选完之后，create-vue会自动生成一个.eslintrc.cjs配置文件、.prettierrc.json或者.prettierrc.mjs格式化配置、还有.eslintignore忽略文件——这三个文件就是你接下来要改的核心，其他的package.json里的依赖和脚本命令也会自动配好，不用你手动npm install一堆东西。

要是你已经有一个没用create-vue搭的Vue3项目，或者是从Vue2升级过来的，没关系，后面的“手动配置核心步骤”也能帮你补全。

手动配置Vue3 ESLint的核心步骤

不管是旧项目升级，还是用了其他脚手架,都可以按照这几步来：

第一步：安装必备的依赖包

打开终端，cd到你的项目根目录，执行npm install或者yarn add、pnpm add的命令（推荐用pnpm，更快更省空间）,安装以下依赖：

• 基础ESLint包：eslint
• Vue3官方ESLint插件：eslint-plugin-vue@9.x（注意必须是9.x及以上版本，才能识别<script setup>）
• 配合Prettier的依赖：prettier、eslint-config-prettier、eslint-plugin-prettier（这三个是黄金搭档，eslint-config-prettier用来关闭ESLint里和Prettier冲突的格式化规则，eslint-plugin-prettier用来把Prettier的规则当成ESLint的错误/警告来显示和修复）
• TypeScript相关依赖（如果用了TS）：@typescript-eslint/eslint-plugin、@typescript-eslint/parser（这两个是TS官方维护的ESLint工具，用来解析TS代码,添加TS专属的代码质量规则）
• 自动导入插件的ESLint支持（如果用了unplugin-auto-import、unplugin-vue-components这些）：比如unplugin-auto-import自带了.eslintrc-auto-import.json生成功能,后面会讲怎么配。

第二步：写好.eslintrc.cjs配置文件

这个文件是ESLint的核心配置，决定了它用什么解析器、识别哪些全局变量、开启哪些规则、报错还是警告，下面给一个通用的、兼顾Vue3、TS、Prettier、自动导入的配置模板，你可以直接复制,然后根据自己的项目修改：

/* eslint-env node */
require('@rushstack/eslint-patch/modern-module-resolution')
module.exports = {
  root: true, // 表示这是项目根目录的ESLint配置，不会再往上找父级配置
  extends: [
    'plugin:vue/vue3-essential', // Vue3官方推荐的基础规则，开启最核心的功能，比如禁止使用Vue2的废弃API
    'eslint:recommended', // ESLint官方推荐的JS基础规则
    'plugin:@typescript-eslint/recommended', // TS官方推荐的基础规则（如果没用TS，删掉这行）
    'plugin:prettier/recommended' // 把Prettier的规则当成ESLint的规则，并且优先用Prettier修复冲突
  ],
  parser: 'vue-eslint-parser', // 必须用这个解析器，才能识别.vue文件里的<template>和<script>
  parserOptions: {
    ecmaVersion: 'latest', // 支持最新的ES语法
    parser: '@typescript-eslint/parser', // 解析.vue文件里的<script>部分的TS代码（如果没用TS，改成'@babel/eslint-parser'或者直接删掉parser这行）
    sourceType: 'module' // 支持ES模块（import/export）
  },
  env: {
    browser: true, // 识别浏览器全局变量，比如window、document
    es2021: true, // 识别ES2021的全局变量，比如Promise.allSettled
    node: true // 识别Node.js全局变量，比如require、__dirname（如果是纯前端项目，可以删掉这行）
  },
  globals: {
    // 这里放自定义的全局变量，比如用了unplugin-auto-import的话，会生成一个.eslintrc-auto-import.json，直接extends进去就行，不用手动写
  },
  rules: {
    // 这里可以覆盖或者新增规则，根据自己的团队习惯调整
    'vue/multi-word-component-names': 'off', // 关闭Vue3官方要求的组件必须是多单词的规则，很多UI组件库比如Element Plus的单文件组件（比如ElButton.vue）也是符合规范的，但这个规则太严格，新手容易踩坑
    '@typescript-eslint/no-explicit-any': 'warn', // 把“禁止使用any”从error改成warn，新手写项目有时候用any过渡是合理的，但不能一直用，警告提醒一下就行
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }], // 把“未使用的变量”从error改成warn，并且忽略以_开头的参数，比如有时候写函数需要占位参数
    'prettier/prettier': [
      'warn',
      {
        // 这里可以覆盖Prettier的规则，和.prettierrc.json里的配置重复没关系，以这里的为准或者以.prettierrc.json为准都行，建议统一放在.prettierrc.json里
        singleQuote: true, // 用单引号
        semi: false, // 不用分号
        trailingComma: 'none', // 不用尾逗号
        printWidth: 100, // 每行代码最多100个字符
        arrowParens: 'avoid' // 箭头函数只有一个参数时不用括号
      }
    ]
  }
}

这里要注意几个关键点：

1. 必须加require('@rushstack/eslint-patch/modern-module-resolution')这行，不然Vite项目里的node_modules解析可能会有问题；
2. parser必须是vue-eslint-parser，不能直接用@typescript-eslint/parser，否则识别不了.vue文件；
3. extends的顺序很重要：最后一个plugin:prettier/recommended必须放在最下面,这样它才能覆盖前面所有和Prettier冲突的规则。

第三步：配好.prettierrc.json或者.prettierrc.mjs

这个文件是Prettier的格式化配置，和.eslintrc.cjs里的rules部分的prettier/prettier配置重复没关系，建议统一放在这里,方便修改：

{
  "singleQuote": true,
  "semi": false,
  "trailingComma": "none",
  "printWidth": 100,
  "arrowParens": "avoid",
  "endOfLine": "lf" // 换行符用LF，避免Windows和Mac/Linux之间的换行冲突
}

第四步：写好.eslintignore忽略文件

这个文件用来告诉ESLint哪些文件不需要检查，比如node_modules、dist这些第三方依赖和打包产物，还有.vscode、.git这些配置文件夹,都是必须忽略的：

node_modules
dist
.vscode
.git
.prettierrc.cjs
.eslintrc.cjs
env.d.ts // 如果是Vite+TS项目，自动生成的环境类型声明文件

第五步：配置编辑器的自动修复

光配好命令行的ESLint还不够，开发的时候要让编辑器自动修复错误，不然每次都要手动敲命令太麻烦，以VS Code为例（现在开发Vue3基本都用VS Code吧）：

1. 安装两个插件：ESLint和Prettier - Code formatter；
2. 打开VS Code的设置（快捷键Ctrl+,或者Cmd+,），搜索“settings.json”，点击“编辑settings.json”，添加以下配置：

   {
   // 编辑器默认格式化工具选Prettier
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   // 保存文件时自动格式化
   "editor.formatOnSave": true,
   // 保存文件时自动用ESLint修复可修复的错误
   "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
   },
   // 禁用Prettier对.vue文件的单独格式化（因为我们已经用ESLint的plugin:prettier/recommended来统一格式化了）
   "[vue]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
   // 同样禁用Prettier对TS/JS文件的单独格式化
   "[typescript]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
   "[javascript]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   }
   }

   配置完之后，重启一下VS Code，打开你的.vue文件，写几行有问题的代码，比如用单引号又用双引号、没加自动导入的ref、用了var,保存文件的时候编辑器就会自动修复大部分问题了。

遇到defineProps这些编译宏报错怎么办？

这是Vue3新手最常见的坑，用create-vue搭的项目其实已经默认解决了——因为eslint-plugin-vue@9.x里有一个env: { 'vue/setup-compiler-macros': true }的规则，但有时候如果手动改了.eslintrc.cjs的extends或者env，可能会把这个规则删掉，这时候只需要在env里加上这行就行：

env: {
  browser: true,
  es2021: true,
  node: true,
  'vue/setup-compiler-macros': true // 识别Vue3的setup编译宏
}

要是你用了eslint-plugin-vue@8.x或者更早的版本，那必须升级到9.x，因为旧版本根本不支持识别<script setup>的编译宏。

用了unplugin-auto-import自动导入ref/reactive还是报错？

unplugin-auto-import是个好东西，能自动导入Vue3的Composition API、Pinia的useStore、Vue Router的useRoute/useRouter这些，不用每次都手动写import { ref, reactive } from 'vue'，但要是没配置好ESLint，这些自动导入的变量还是会飘红“未定义”。

解决办法很简单，利用unplugin-auto-import自带的生成ESLint全局变量文件的功能：

1. 打开你的Vite配置文件vite.config.ts或者vite.config.js，找到unplugin-auto-import的配置部分，加上eslintrc: { enabled: true }：

   import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({ plugins: [ vue(), AutoImport({ imports: ['vue', 'vue-router', 'pinia'], // 自动导入的模块 dts: 'src/auto-imports.d.ts', // 生成TS类型声明文件 eslintrc: { enabled: true, // 启用生成ESLint全局变量文件 filepath: './.eslintrc-auto-import.json', // 生成的文件路径 globalsPropValue: true // 全局变量的属性值设为true，表示可以读写 } }) ] })

重启一下Vite开发服务器，项目根目录就会自动生成一个`.eslintrc-auto-import.json`文件；
3. 打开你的`.eslintrc.cjs`文件，在`extends`数组里加上这个生成的文件：
```javascript
extends: [
  'plugin:vue/vue3-essential',
  'eslint:recommended',
  'plugin:@typescript-eslint/recommended',
  'plugin:prettier/recommended',
  './.eslintrc-auto-import.json' // 加上这行
]

再重启一下VS Code,飘红就会消失了。

团队协作时怎么统一ESLint规则？

团队协作时，每个人的编辑器配置可能不一样，这时候要确保大家用的是同一套ESLint规则,最好的办法是：

1. 把.eslintrc.cjs、.prettierrc.json、.eslintignore这三个文件提交到Git仓库；
2. 在package.json里加两个脚本命令：

   {
   "scripts": {
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore", // 手动检查并修复所有文件的ESLint错误
    "lint:fix": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --ignore-path .gitignore" // 只检查错误，不自动修复
   }
   }

3. 在Git提交代码前，强制运行lint:fix命令，确保提交的代码没有ESLint错误——可以用husky和lint-staged这两个工具来实现：
   • 先安装husky和lint-staged：pnpm add husky lint-staged -D；
   • 启用husky：npx husky install；
   • 添加pre-commit钩子：npx husky add .husky/pre-commit "npx lint-staged"；
   • 在package.json里加lint-staged的配置：

     {
     "lint-staged": {
     "*.{vue,js,jsx,cjs,mjs,ts,tsx,cts,mts}": [
      "eslint --fix"
     ]
     }
     }

     这样配置之后，每次你提交Git代码前，lint-staged都会自动检查你这次修改的文件，并用ESLint修复可修复的错误，如果有不可修复的错误，就会阻止你提交代码,确保团队的代码风格一致。

Vue3的ESLint配置其实没有想象中那么难，核心就是用对解析器和插件、注意extends的顺序、配好编辑器的自动修复、解决好编译宏和自动导入的问题，要是你刚搭项目，直接用create-vue官方脚手架就行，它已经帮你填了一半的坑；要是是旧项目升级，按照上面的“手动配置核心步骤”来,很快就能搞定。

最后还要提醒一句：ESLint规则不是越严格越好，要根据团队的开发习惯和项目的紧急程度来调整，比如新手项目可以把一些太严格的规则从error改成warn，等大家熟悉了之后再慢慢收紧,不然反而会影响开发效率。