写 Vue 项目也有一阵子了前面几篇笔记记的大多是组件、路由这一类的业务代码今天这篇笔记有点特别——不谈业务先把 Vetur、ESLint、Prettier 三个工具在 VS Code 里的配合关系理顺。很多新手遇到的“代码高亮没有”“保存不格式化”“保存后单引号全变双引号”这类问题本质都是环境没配好而不是代码写错了。这篇文章不是只丢给你几段配置而是把 Vetur、ESLint、Prettier 各自做什么、互相怎么配合、碰到冲突怎么排查一条条讲清楚。想从里面有收获的朋友大概分三类刚接触 Vue 和 VS Code 不知道装什么的新手装了插件却始终配不出理想效果的人接手上一个 Vue 2 老项目需要补齐工具链的开发者。我会按照自己实际配置时的顺序来写尽量让每一步都能直接复现。1. 三个工具各管一段别把它们理解成同一件事很多人一开始会把 Vetur、ESLint、Prettier 混在一起觉得“都是插件嘛装完就完事”。其实这三者的边界非常清楚如果搞混了后面所有配置都会变得莫名其妙。我见过不少人在群里问“为什么我装了 Prettier代码里的错误还是不会提示”一听就知道他把格式化工具和代码检查工具搞混了。1.1 Vetur编辑器里识别 .vue 文件的“翻译官”VS Code 虽然对各种语言的支持很出色但它原生并不能直接理解 .vue 文件。一个 .vue 文件里同时包含 template、script、style 三部分每一部分用的语法还不同。在没有任何工具的状态下打开它你看到的通常是一整片没有高亮的纯文本补全、跳转定义这些功能更是无从谈起。Vetur 做的事情就是把 .vue 文件拆解成 VS Code 能看懂的结构分别交给对应的语言处理器来处理template 部分当作 HTML 来识别script 部分当作 JavaScript或者 TypeScript来识别style 部分当作 CSS/SCSS/Less 来识别。装上它之后.vue 文件才能获得语法高亮、代码片段、智能补全、悬停提示、跳转定义等基础编辑能力。需要特别说明的是Vetur 官方文档自己都写明推荐用于 Vue 2 项目。Vue 3 项目现在更建议使用 Volar。这篇笔记虽然用的是 Vetur但对应的 Vue 2 开发场景依然大量存在尤其是维护中的老项目和很多公司的存量代码这套配置的学习成本完全值得付。1.2 ESLint管代码“对错”的质检员ESLint 是一个代码检查工具可以理解成编辑器里的质检员。它关注的核心是代码是否存在问题声明了变量却没用、调用了不存在的全局函数、写错了某些 Vue 模板中的指令写法、犯了某种不建议使用的语法错误等等。ESLint 单独使用时的检查范围是纯 JavaScript 文件到了 Vue 项目里还需要配合 eslint-plugin-vue 这个插件把 .vue 文件中的 template、script 两部分也纳入检查。它背后运行的是一套规则集合其中既有 ESLint 自带的核心规则也有 Vue 插件提供的 Vue 专属规则。如果代码违反规则编辑器会立刻画出红色波浪线保存时还能自动尝试修复。1.3 Prettier管代码“长相”的美工Prettier 和上面两个都不同它完全不管代码用得好不好、有没有逻辑问题只关心代码看起来整不整齐。同一段代码有人喜欢单引号有人喜欢双引号有人习惯每行末尾加分号有人习惯不加有人喜欢属性换行排有人喜欢紧凑地放一行。这些纯风格的差异用 Prettier 可以一刀切式地统一。团队协作时Prettier 的价值会被放大很多大家在同一个配置下写字提交代码时就不会出现大段大段的格式差异git diff 干净很多代码评审时也不会被无关的格式修改干扰注意力。1.4 为什么一定要组合使用一个管识别、一个管对错、一个管格式三者各司其职缺一个体验都差一截。少了 Vetur写 .vue 文件和写纯记事本没什么区别少了 ESLint潜在的错误要等跑起来才发现少了 Prettier代码风格要靠每个成员手动维护很难真正统一。这三个工具的组合方式也是 Vue CLI 和 Vite 官方脚手架默认推荐的那一套只是很多新人不理解心想装都装了为什么还要配其实光装不配它们不一定能真的协调工作后面这些配置就是为了让它们“点头合作”。2. 环境准备与 Vetur 的安装配置为了保证这篇笔记的可复现性我会从新建一个 Vue 2 项目开始再在 VS Code 里安装并设置 Vetur。如果你已经有项目跳过创建步骤直接看 Vetur 配置就好。2.1 用 Vue CLI 创建一个演示项目如果你没有现成的 Vue 项目最快捷的方式是用 Vue CLI 创建一个npm install -g vue/cli vue create vue-vetur-demo创建过程中会有几个交互选项。这里有个关键技巧选择手动配置Manually select features并且在功能列表里把 Linter / Formatter 勾上。这样 Vue CLI 会在生成项目的同时自动安装 ESLint 相关依赖后面我们只需要做增量配置省掉不少手工安装的步骤。如果你选择的是默认配置项目里不会有 ESLint 相关的文件后面就需要自己手动补装这是很多新手在第一步就悄悄埋下的坑。我用默认配置新建过几个练习项目后来发现 .vue 文件里没有任何检查提示还以为是插件坏了实际是项目里根本没有 eslint 的依赖VS Code 里的 ESLint 插件找不到对应的 CLI 工具自然不工作。2.2 安装 Vetur 插件及基础设置在 VS Code 扩展面板里搜索“Vetur”认准发布者是 octref。安装后重启窗口。安装完之后重点检查这几项设置。在扩展面板找到 Vetur进入 Extension Settings设置项推荐值作用vetur.validation.templatetrue在模板部分做 HTML 校验标签不合法能立刻看到vetur.validation.scripttrue在 script 部分做 JS 校验未定义变量等高亮提示vetur.validation.styletrue在 style 部分做 CSS 校验vetur.completion.autoImporttrue自动导入组件vetur.useWorkspaceDependenciestrue优先使用项目内 node_modules 里的依赖最后一项容易忽略。如果不打开Vetur 会优先去全局环境找依赖如果项目依赖版本和全局依赖版本不一致解析出来的效果就可能不一样。推荐设为 true原因是所有人都是用同一套项目依赖解析出来的效果才一致。2.3 验证 Vetur 是否生效完成上述配置后打开一个 .vue 文件正常情况下你能观察到三个现象最直观的是语法高亮template 里的标签、script 里的 JS、style 里的 CSS 呈现出不同配色其次在模板里书写v-if、v-for等指令时编辑器会出现对应补全列表最后鼠标悬停在组件的 props 上能跳转到定义位置。如果这些现象都没发生先不要急着往下走检查扩展是否已启用确认 VS Code 窗口是不是重启过再确认是不是把工作区打开到了项目根目录而不是某个子目录。Vetur 对工作区根目录的识别比较敏感打开的文件夹层级不对插件容易“装死”。3. ESLint 接入让 Vue 项目的每一行错误都显示在编辑器里接下来配置 ESLint。与 Vetur 相比ESLint 的依赖数量多不少而且配置文件的字段门槛也更高我会把每一步都说明白。3.1 安装依赖假设你没有通过 Vue CLI 的 Linter 选项把 ESLint 装好敲下面这行命令npm install -D eslint eslint-plugin-vue prettier eslint-config-prettier这里出现 prettier 和 eslint-config-prettier 不用惊讶。ESLint 和 Prettier 天然存在一些重复领域ESLint 有缩进规则Prettier 也管缩进ESLint 有引号规则Prettier 也管引号。如果两边规则冲突代码保存时会陷入“ESLint 让你改回去Prettier 又改回来”的拉扯。eslint-config-prettier 的作用就是把 ESLint 中所有和 Prettier 重叠的格式类规则关掉让格式问题统一交给 Prettier。这是解决两类工具冲突的官方推荐方案。3.2 根目录创建 .eslintrc.js在项目根目录新建.eslintrc.js写入以下配置module.exports { root: true, env: { browser: true, node: true, es2021: true }, extends: [ eslint:recommended, plugin:vue/essential, prettier ], parserOptions: { parser: babel-eslint, ecmaVersion: 2021, sourceType: module }, rules: { no-console: process.env.NODE_ENV production ? warn : off, no-debugger: process.env.NODE_ENV production ? warn : off } }逐块解释一下root: true表示这个配置文件是最顶层的 ESLint 配置告诉 ESLint 不要再向父目录找配置文件。放到项目根目录之后多人协作时会避免各自电脑上的上级目录配置干扰到项目检查结果这一项在 Vue 项目里建议保留。env声明代码的运行环境。浏览器环境里会有 window、document 这些全局变量Node 环境里会有 require、module 这些全局变量。如果不声明ESLint 会把它们视作“未定义变量”报错。extends引入规则集。eslint:recommended是 ESLint 内置的核心推荐规则plugin:vue/essential是 eslint-plugin-vue 提供的必备规则侧重于防止 Vue 中容易出错的写法prettier就是前面下载的 eslint-config-prettier放在数组最后负责关闭有冲突的格式规则。parserOptions这里有个容易踩的坑。Vue 2 项目里如果用babel-eslint你需要先单独安装它npm install -D babel-eslint。它让 ESLint 能解析现代 JavaScript 语法。如果你用的是较新的构建工具链也可以换成babel/eslint-parser配置思路不变。rules用来覆盖或新增单条规则。上面写的是 Vue 项目里最常见的两项生产环境编译时把 console 和 debugger 作为警告提示而开发环境下保留日志输出便于调试。3.3 VS Code 中的 ESLint 插件与工作区设置光有依赖不行还需要在 VS Code 中安装 ESLint 扩展扩展 ID 是dbaeumer.vscode-eslint。装好后它会在每次打开文件时自动读取项目内的.eslintrc.js在不符合规则的地方显示波浪线。这里有一个很重要的组合逻辑任何配置都不要写到全局 settings.json因为项目的 ESLint 配置应该跟着项目走。团队里每个人的全局配置五花八门如果你把 ESLint 相关设置写进全局提交到别的项目时很容易干扰到那个项目的检查结果。所以下文要讲的 settings全部放到.vscode/settings.json这种工作区级别文件里还可以提交到 git 让队友同步使用。4. Prettier 配置让代码格式不再靠手Prettier 的配置思路和 ESLint 不太一样。它本身没有那套庞大的规则体系核心配置项大概只有十几个所以设置起来反而轻松。4.1 安装与准备安装 Prettier 有两条路径一是作为 npm 依赖配合编辑器命令使用二是给 VS Code 安装 Prettier 扩展由编辑器直接调用。在实际工作中通常两者都要npm 依赖给项目提供确定版本VS Code 扩展负责在编辑器里把格式化能力表现出来。npm install -D prettier然后安装扩展esbenp.prettier-vscode。4.2 核心配置项一张表掌握在项目根目录创建.prettierrc这里的可选项非常多我挑实际项目中最常改的几个说明配置项默认值推荐值说明printWidth80100单行超过这个宽度就换行80 在多数宽屏上偏短100 更符合前端项目的习惯tabWidth22每一级缩进的空格数Vue 官方风格就是 2 空格singleQuotefalsetrue字符串默认用单引号避免手误写出的双引号与项目内置规则冲突semitruetrue语句末尾是否加分号trailingCommaes5all多行结构最后一个元素后是否加逗号all 在 git diff 时更友好bracketSameLinefalsetrueVue 组件标签的是否与最后一个属性同行arrowParensalwaysalways箭头函数参数是否加括号始终加上某些环境下风格更一致trailingComma值得多说一句当对象或数组有多行时最后一个元素后保留逗号。这么做的好处是以后在末尾新增一行时git diff 只会显示新增的那一行而不是出现“上一行多了逗号、这一行新增”两处改动。这是经验值经常做代码评审的人对这个细节会比较敏感。4.3 写一份 .prettierrc 示例项目的.prettierrc大致长这样{ printWidth: 100, tabWidth: 2, singleQuote: true, semi: true, trailingComma: all, bracketSameLine: true, arrowParens: always }如果想要更细的工程化配置还可以把忽略文件规则放进.prettierignore比如dist、node_modules、package-lock.json这些不参与格式化的目录或文件。这样格式化时不会去动构建产物也不会产生无意义的巨大 diff。4.4 让 Prettier 和 ESLint 站在同一边上面第 3.1 节我提过eslint-config-prettier它的作用就是关掉 ESLint 里跟 Prettier 重复的格式规则。现在你还要决定Prettier 到底扮演什么角色。两种常见做法只把 Prettier 当作编辑器格式化工具ESLint 只负责报告代码质量问题。这种情况下eslint-config-prettier已足够ESLint 不再对格式指手画脚两者并行不悖。借助eslint-plugin-prettier把 Prettier 当成 ESLint 的一条规则来运行让格式问题也能以 ESLint 报错的形式出现。这种方式更严格但每次修复时等于让 ESLint 先跑一个完整格式化流程速度会慢一些规则复杂时也会让人觉着冗余。如果是个人学习或小团队项目我推荐第一种简单直接。如果项目很正式团队要求提交代码前所有格式问题都通过 ESLint 筛一遍第二种更稳。真要选第二种需要再装一个eslint-plugin-prettier并在.eslintrc.js里加一行extends: [ eslint:recommended, plugin:vue/essential, plugin:prettier/recommended ]plugin:prettier/recommended这个组合包已经包含了eslint-config-prettier和eslint-plugin-prettier的功能写一条就够。5. settings.json 集成保存即格式化配置进行到这里工具链已经具备检查与格式化能力但还缺最后一根引线怎么在编辑操作中把它们触发起来。答案是 settings.json 集成。5.1 工作区配置还是全局配置怎么选VS Code 的设置有两类层次全局的用户设置和项目内.vscode/settings.json的工作区设置。工作区设置会覆盖全局而且可以放进版本管理跟随项目一起分发。正式做法是与代码风格相关的设置全部放工作区个人偏好比如字体大小、主题色放全局。这样同一个仓库里不管你换几次电脑也不管队友的 VS Code 怎么自定义打开项目后编辑器表现一致格式化行为和检查行为不会再因环境不同而飘忽不定。5.2 一套可直接落地的 settings.json在项目的.vscode/目录下新建settings.json填入{ editor.defaultFormatter: esbenp.prettier-vscode, editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.eslint: true }, eslint.validate: [vue, javascript, javascriptreact, html], eslint.format.enable: true, [javascript]: { editor.defaultFormatter: esbenp.prettier-vscode }, [vue]: { editor.defaultFormatter: esbenp.prettier-vscode }, [json]: { editor.defaultFormatter: esbenp.prettier-vscode } }挑几个关键项说明editor.formatOnSave保存时自动调用默认格式化器这是“保存即格式化”的主开关。editor.codeActionsOnSave.source.fixAll.eslint保存时自动执行一次 ESLint 的 fix 操作能自动修复的规则比如去掉多余空格、补上缺失分号会在这一瞬间完成。eslint.validate告诉 ESLint 插件要检查哪些类型。默认只检查 JavaScript加上vue才能让 .vue 文件里的 script 和 template 参与检查。[vue]段把默认格式化器指定为 Prettier。这里其实有个历史小坑早期很多教程会让 Vetur 自己格式化 vue 文件于是保存时 Vetur 先格式化一次ESLint 的 fix 又跑一次两层操作叠加会把光标顶到文件末尾体验极其痛苦。后来大家统一把格式化交给 PrettierVetur 只做高亮和补全世界清净了。5.3 实测效果设置完成后随便改一个 .vue 文件比如把一段 JS 里的单引号手改成双引号保存。可以看到引号立刻被 Prettier 改回单引号如果再故意把一个v-for指令的 key 去掉ESLint 会在编辑器里画出红色波浪线保存时 codeActions 会自动报一个可修复的错误。整个过程不用你敲第二条命令。如果保存后没有任何变化多半是editor.formatOnSave没被启用或者文件类型没有落到[vue]的匹配范围里。把文件右下角的语言模式点开确认显示的是 Vue而不是纯文本这是很基础但很常见的疏漏。6. 实测踩坑三者打架的典型案例排查这里总结几个我在实际项目中一一撞过的坑。这些问题的共同特点是几个工具规则冲突时表现出的诡异现象排查思路比单个答案更值得记住。6.1 案例一Prettier 把单引号改成双引号ESLint 又要求单引号症状保存文件后代码里的引号全部变成双引号但 ESLint 立刻在这些位置画红线来回保存都稳定复现。原因Prettier 默认的singleQuote是 false也就是默认用双引号而 ESLint 推荐规则里quotes要求单引号。两边规则不一致保存时先被 Prettier 改成双引号随后 ESLint 又提示“应该用单引号”。解决在.prettierrc中把singleQuote设为 true让 Prettier 向 ESLint 看齐同时确认.eslintrc.js的extends数组里包含了prettier或plugin:prettier/recommended这样 ESLint 不会强制再抢格式规则。多数情况下这两步操作完问题即刻消失。6.2 案例二模板缩进一会儿 2 空格一会儿 4 空格症状.vue 文件里 template 的部分看起来是 4 空格缩进script 部分却是 2 空格两条缩进规则互相打架。原因template 的缩进可能被 ESLint 的vue/html-indent规则所控制而 script 部分的缩进由 Prettier 控制如果你在.eslintrc.js里没有把冲突规则关干净两边就各按各的来。解决分两步。第一步在.prettierrc把tabWidth固定为 2第二步在.eslintrc.js的 rules 里显式关闭与缩进相关的重复规则比如vue/html-indent: off。如果你选了plugin:prettier/recommended组合这类冲突理论上不会再出现但遇到老项目里的历史配置时直接关掉对应规则是最快的兜底方案。6.3 案例三保存时光标被顶到文件末尾症状每次按 CtrlS 保存 .vue 文件光标跃到文件最后一行尤其编辑长文件时特别烦人。原因这是多个格式化器同时抢占的经典触因。常见组合是Vetur 同时负责 .vue 文件的格式化而 Prettier 也被设为默认格式化器保存时两个格式化器依次执行编辑器光标定位逻辑被打乱。解决只在设置里保留一个格式化来源。我的做法是在[vue]语言段把 defaultFormatter 明确指定为 Prettier同时在 Vetur 扩展设置里把vetur.format.enable关掉。原理上Vetur 继续管语法高亮和补全格式化整个交给 Prettier只留一个执行者后光标问题基本消失。6.4 顺带一提Vue 3 用户请切换 Volar写这篇笔记时我默认的是 Vue 2 项目场景。如果你准备用 Vue 3 开启新项目现在官方强烈推荐使用 Volarvue.volar来替代 Vetur。Vetur 对 Vue 3 语法的支持更新比较慢Volar 的解析方式也更贴近 Vue 3 的编译器实现。切换的逻辑就是卸载 Vetur装上 Volar然后把[vue]的 defaultFormatter 继续指向 PrettierESLint 配置依旧不变。这套先确认格式化源、再确认检查工具的思维到了 Vue 3 依然成立。关于这个话题还有个小技巧想分享团队项目里把.vscode文件夹和.eslintrc.js、.prettierrc一起提交进 git新成员 clone 完代码VS Code 打开项目格式化规则自动生效不需要任何人再花一上午去装环境。我在带新人的时候这一步省下来的沟通成本相当可观。配置过程看着零散真正理解了三个工具的边界后面遇到任何报错都不慌。你第一次配置 Vetur、ESLint、Prettier 时遇到过什么奇葩问题可以分享一下说不定下一个踩坑的人就靠你的经验救回来。