从0到1配置eslint-plugin-vue：手把手带你搭环境
为什么偏偏是eslint-plugin-vue？
你可能会说：“我已经用了eslint，为啥还要专门装个vue的插件？” 这就要说到Vue文件的特殊性了——一个.vue文件里既有模板，又有脚本，可能还有样式，普通的eslint只能处理JavaScript，对Vue的模板语法完全“看不懂”。而eslint-plugin-vue就是专门为Vue文件设计的，它能解析模板里的v-for循环、v-if判断是否合理，检查组件props是否定义规范，甚至能发现script里没用到的import。我之前带的一个5人小团队，没配这个插件时，每次code review光挑格式问题就要花20分钟，后来统一配置后，这部分时间直接省下来了，团队沟通效率都高了不少。
3步完成基础配置，5分钟跑通检查
第1步：安装依赖（别漏了核心包）
首先得确保你的项目里已经有Node.js和npm（或yarn），然后打开终端，进入项目根目录，运行安装命令。这里要注意，eslint-plugin-vue需要搭配eslint本体和Vue的解析器，缺一不可。我推荐用Vue3项目举例，如果你用Vue2，把下面的vue-eslint-parser换成对应版本就行：
# 安装核心依赖
npm install eslint eslint-plugin-vue vue-eslint-parser save-dev
这里有个小细节：一定要指定版本范围，比如eslint-plugin-vue@^9.0.0（最新版），避免npm自动安装不兼容的版本。我之前就踩过坑，装了个太旧的版本，结果不支持Vue3的语法，排查半天才发现是版本问题。
第2步：编写配置文件（核心参数详解）
安装完成后，在项目根目录新建.eslintrc.js文件，这是eslint的核心配置文件。别担心看不懂，我带你拆解关键参数，照着抄都能生效：
module.exports = {
root: true, // 告诉eslint这是根配置，不继承父目录的配置
env: {
browser: true, // 启用浏览器环境变量（如window、document）
es2021: true // 支持ES2021语法
},
extends: [
"eslint:recommended", // 启用eslint自带的推荐规则
"plugin:vue/vue3-essential" // Vue3基础规则（必选）
],
parserOptions: {
parser: "@babel/eslint-parser", // 用babel解析ES6+语法（如果用了TypeScript，换成@typescript-eslint/parser）
sourceType: "module" // 支持ES模块（import/export）
},
rules: {
// 这里写自定义规则，0=关闭，1=警告，2=错误
"vue/multi-word-component-names": "off", // 关闭组件名必须多单词的检查（新手友好）
"no-console": process.env.NODE_ENV === "production" ? "warn" "off" // 生产环境警告console，开发环境关闭
}
};
这里最关键的是extends字段，它决定了要启用哪些预设规则。eslint-plugin-vue提供了几种预设，我整理了一张表格，你可以根据项目阶段选择：
| 预设名称 | 包含规则数量 | 适用场景 | 推荐指数 |
|---|---|---|---|
| plugin:vue/vue3-essential | ~50条 | Vue3基础项目，只包含必要规则（如防止语法错误） | ★★★★★（新手首选） |
| plugin:vue/vue3-strongly-recommended | ~80条 | Vue3项目，增加代码风格规则（如组件名格式） | ★★★★☆（团队协作推荐） |
| plugin:vue/vue3-recommended | ~100条 | Vue3大型项目，最严格的规则（如强制使用TypeScript） | ★★★☆☆（成熟项目可选） |
第3步：集成编辑器，实时看到报错（避免提交后才发现问题）
光配置文件还不够，最好能在写代码时就实时看到错误提示，这样不用等到运行命令才发现问题。以VSCode为例，你需要先安装两个插件：ESLint（微软官方的）和Vetur（Vue文件支持插件），然后打开VSCode的设置文件（按Ctrl+Shift+P，输入settings.json），添加这几行配置：
{
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true // 保存时自动修复eslint能修复的错误
},
"eslint.validate": [
"javascript",
"vue" // 告诉eslint校验Vue文件
]
}
这样一来，你在写Vue文件时，如果模板里有未闭合的标签，或者script里有未使用的变量，VSCode会直接在代码下方标红，保存时还能自动修复缩进、引号格式等问题。我自己的项目里就开了这个功能，现在写代码基本不用手动调整格式，效率高多了。
实战避坑指南：解决90%的常见问题
坑1：Prettier和eslint-plugin-vue“打架”，格式自动变来变去
你有没有遇到过这种情况：用Prettier格式化代码后，eslint报错；用eslint修复后，Prettier又改回来？这是因为两者的规则有冲突，比如Prettier默认用双引号，而eslint-plugin-vue的某些规则强制单引号。解决办法很简单，安装一个“翻译官”插件，让它们“和平共处”：
# 安装解决冲突的依赖
npm install eslint-config-prettier eslint-plugin-prettier save-dev
然后在.eslintrc.js的extends里添加这两个规则：
extends: [
"eslint:recommended",
"plugin:vue/vue3-essential",
"plugin:prettier/recommended", // 整合Prettier和eslint
"eslint-config-prettier" // 关闭eslint中与Prettier冲突的规则
]
我之前帮朋友的项目解决过这个问题，他之前每次保存都要手动调整格式，加了这几行配置后，保存时Prettier和eslint各司其职，再也没出现过格式冲突。
坑2：自定义规则不生效，配置了半天没反应？
有时候你在.eslintrc.js的rules里加了自定义规则，比如禁止使用console.log：
rules: {
"no-console": "error" // 理论上console.log会报错
}
结果运行npm run lint发现没反应，这可能有3个原因，按优先级排查：
vue/开头，比如检查模板里未使用变量的规则是vue/no-unused-vars，而不是普通的no-unused-vars。我之前就把vue/no-unused-components写成vue/no-unused-component（少个s），排查了半小时才发现。extends里的预设规则优先级比你的自定义规则高，可能会覆盖。解决办法是把rules写在extends后面，或者在规则值里加"off"先关闭预设规则。.eslintignore文件，看看是不是不小心把你的Vue文件加进去了（比如忽略了src/views/目录）。坑3：Vue2项目用了Vue3的规则，报错“parserOptions.project”
如果你用的是Vue2，但extends里配了plugin:vue/vue3-essential，就会出现这种错误。这是因为Vue3的规则依赖Vue3的解析器，而Vue2需要用vue-eslint-parser@7.x版本（Vue3需要8.x以上）。解决办法很简单：
eslint-plugin-vue@8.x和vue-eslint-parser@7.x，extends用plugin:vue/essential（不带vue3）eslint-plugin-vue@9.x和vue-eslint-parser@8.x，extends用plugin:vue/vue3-essentialVue官方文档里也提到过这个版本对应关系，你可以去看看详细说明（eslint-plugin-vue安装指南），里面有不同Vue版本的配置示例。
坑4：模板里的v-for不写key，eslint却不报错？
按理说，v-for必须加:key，不然eslint-plugin-vue应该报错，但有时候就是不提示。这是因为你可能用了太基础的预设规则。比如vue3-essential只检查“会导致运行错误”的问题，而v-for缺key属于“性能问题”，需要开启更严格的预设。解决办法是把extends里的vue3-essential换成vue3-strongly-recommended，这个预设会强制检查v-for的key、组件名格式等规则。我 团队项目都用这个预设，能提前规避不少潜在问题。
你按这些步骤操作下来，eslint-plugin-vue应该就能稳定运行了。如果遇到其他奇怪的问题，别慌，先看看是不是版本不兼容（去npm官网查依赖的最新版本），或者配置文件里有没有拼写错误。如果试了这些方法还有问题，欢迎在评论区告诉我你的具体报错信息，我来帮你一起分析！
你有没有遇到过这种情况？项目里明明配了eslint-plugin-vue，结果一跑检查，控制台哗啦啦冒出一堆node_modules里的报错，或者dist目录下的打包文件也被扫出来说格式不对——这些文件根本不是你写的，检查它们纯属浪费时间。这时候就该让eslint-plugin-vue“选择性失明”了，专门忽略那些不需要检查的文件，方法其实超简单，跟.gitignore忽略不需要提交的文件差不多。
具体操作是在项目根目录新建一个叫.eslintignore的文件，然后把你想跳过的文件或目录一行一个列进去就行。比如node_modules这种第三方依赖目录，肯定不用检查，直接写node_modules/；还有打包生成的dist目录，里面都是编译后的代码，也没必要扫，加上dist/；如果是临时写的测试文件，比如src目录下的__tests__文件夹，或者根目录的debug.js，都可以直接列进去。我之前带的项目没配这个文件时，eslint检查一次要等30秒，加了.eslintignore忽略掉node_modules和dist后，速度直接提到5秒内，效率一下子就上来了。
不过这里有个小细节得注意：写路径的时候别画蛇添足加“./”，比如想忽略src/test/目录，直接写src/test/就行，不用写成./src/test/，不然可能识别不到。我之前就踩过这个坑，明明列了路径却没生效，后来发现是多写了个点，折腾半天才找到原因。另外如果某个特定文件需要忽略，比如根目录的temp.log，直接写temp.log就行；要是想忽略所有.log文件，就用*.log——总之跟.gitignore的语法基本一致，用过git的话上手特别快。
安装eslint-plugin-vue时需要指定版本吗？
指定版本范围，例如使用^9.0.0（最新稳定版）。不同版本的eslint-plugin-vue对Vue2和Vue3的支持不同，且可能存在规则差异，未指定版本可能导致npm自动安装不兼容版本，比如旧版本不支持Vue3的语法，或与eslint本体版本冲突。
如何让eslint-plugin-vue忽略某些不需要检查的文件？
可以在项目根目录创建.eslintignore文件，列出需要忽略的文件或目录，格式与.gitignore类似。例如忽略node_modules/目录、dist/打包文件，或特定的测试文件（如/__tests__/.js）。配置后，eslint-plugin-vue将跳过这些文件的检查。
Vue2项目和Vue3项目的eslint-plugin-vue配置有什么区别？
主要区别在解析器和预设规则：Vue3项目需安装vue-eslint-parser@8.x以上版本，预设规则使用plugin:vue/vue3-essential（或对应Vue3的其他预设）；Vue2项目则需使用vue-eslint-parser@7.x版本，预设规则使用plugin:vue/essential（不带“vue3”前缀）。 Vue3的语法需要eslint-plugin-vue@9.x以上版本支持。
eslint-plugin-vue能自动修复所有报错吗？
不能。eslint-plugin-vue的自动修复功能（如通过eslint fix命令）仅支持部分规则，例如缩进、引号格式、未使用的import等“可自动修复”规则；而模板中未闭合的标签、v-for缺少key、props类型错误等“逻辑类”错误需要手动修改。具体可修复规则可查看eslint-plugin-vue官方文档的规则说明。
配置完成后，如何在CI/CD流程中集成eslint-plugin-vue检查？
可在package.json的scripts中添加检查命令，例如”lint”: “eslint src//.{js,vue}”，然后在CI/CD配置文件（如GitHub Actions的.github/workflows/ci.yml）中添加步骤：运行npm run lint，若检查失败则阻断构建流程。这样能确保代码提交前符合规范，避免不规范代码进入仓库。
