VSCode + ESLint 高效代码规范实战 — 一键保存自动修复与规则定制

1. 为什么需要代码规范工具刚入行前端时我最头疼的就是同事留下的风格迥异的代码——有的缩进用空格有的用Tab有人写分号有人不写单引号和双引号随机出现。后来团队引入了ESLint配合VSCode的自动修复功能这些问题终于得到了根治。代码规范工具的核心价值在于统一团队风格避免因个人习惯引发的格式战争提前暴露错误在保存文件时就发现潜在语法问题提升可维护性规范的代码就像排版整齐的书籍阅读体验更好减少CR负担不用再在代码评审时争论缩进问题我在多个项目中实测发现配置得当的ESLintVSCode组合可以消除80%以上的基础语法错误和风格问题。特别是在Vue/React这类现代前端项目中当文件同时包含JS/HTML/CSS时规范工具的作用更加明显。2. 基础环境搭建2.1 必备工具安装首先确保你的VSCode是较新版本建议≥1.60然后安装这些核心插件# 全局安装ESLint如果项目已有可跳过 npm install -g eslint在VSCode扩展商店搜索安装ESLint微软官方出品Prettier可选但建议安装VeturVue项目必需安装后记得重启VSCode让插件生效。我遇到过好几次插件不工作的情况重启后就好了。2.2 项目级ESLint配置在项目根目录执行如果已有.eslintrc.*文件可跳过# 初始化ESLint配置 eslint --init根据项目类型选择配置Vue项目选To check syntax and find problemsReact项目选To check syntax, find problems, and enforce code style建议选择Airbnb或Standard作为基础规则集初始化完成后会生成.eslintrc.js文件这是我的Vue项目配置示例module.exports { env: { browser: true, es2021: true, }, extends: [ plugin:vue/essential, airbnb-base, ], parserOptions: { ecmaVersion: 12, sourceType: module, }, plugins: [ vue, ], rules: { // 自定义规则写在这里 no-console: process.env.NODE_ENV production ? warn : off, vue/multi-word-component-names: off }, };3. VSCode深度配置3.1 settings.json核心配置按Ctrl,打开设置点击右上角打开设置(json)添加这些关键配置{ // 基础配置 editor.codeActionsOnSave: { source.fixAll.eslint: true }, eslint.validate: [ javascript, javascriptreact, typescript, typescriptreact, vue, html ], // 高级配置 eslint.format.enable: true, eslint.run: onType, eslint.alwaysShowStatus: true, editor.formatOnSave: false, // 避免与Prettier冲突 // Vue项目特殊配置 eslint.options: { extensions: [.js, .vue] }, vetur.validation.template: false // 禁用Vetur的模板检查 }常见坑点排查如果Vue文件不生效检查是否安装了Vetur插件如果TypeScript文件不检查需要安装typescript-eslint/parser保存时没反应检查右下角ESLint状态栏是否报错3.2 保存时自动修复要实现保存时自动修复关键在于这两个配置editor.codeActionsOnSave: { source.fixAll.eslint: true }, editor.formatOnSave: false实测发现很多同学配置无效是因为同时开启了Prettier的formatOnSave没有禁用VSCode自带的格式化功能.eslintrc.js中存在语法错误建议的调试步骤右下角查看ESLint是否激活打开输出面板(CtrlShiftU)选择ESLint日志创建一个明显不符合规则的代码如未使用的变量观察保存时是否自动修复4. 规则定制实战4.1 修改现有规则在.eslintrc.js的rules对象中添加自定义规则rules: { // 生产环境禁用console no-console: process.env.NODE_ENV production ? error : warn, // 允许使用运算符 no-plusplus: off, // 自定义缩进规则 indent: [error, 2, { SwitchCase: 1, VariableDeclarator: first }], // Vue相关规则 vue/html-self-closing: [error, { html: { void: always, normal: never, component: always } }] }4.2 团队规范配置技巧对于团队项目建议采用扩展配置的方式创建共享配置包npm init eslint/config发布到私有npm仓库或作为git子模块在项目中继承extends: [ our-team/eslint-config-vue ]我主导过的项目中最有用的几条规则强制函数最大行数不超过50行禁止直接修改函数参数要求Promise必须有catch处理组件props必须定义类型校验5. 高级应用场景5.1 配合Prettier使用虽然ESLint也能处理格式问题但Prettier的格式化更专业。配置要点安装依赖npm install --save-dev prettier eslint-config-prettier修改ESLint配置extends: [ prettier // 必须放在最后 ]添加.prettierrc.jsmodule.exports { semi: true, singleQuote: true, printWidth: 100, trailingComma: all };5.2 TypeScript项目配置对于TS项目需要额外配置extends: [ plugin:typescript-eslint/recommended ], parser: typescript-eslint/parser, plugins: [typescript-eslint], rules: { typescript-eslint/no-explicit-any: off }5.3 自定义插件开发当现有规则不满足需求时可以开发自定义插件创建插件骨架npx yo eslint:plugin添加规则文件module.exports { meta: { type: problem, docs: { description: 禁止使用特定的变量名, } }, create(context) { return { Identifier(node) { if (node.name oldVar) { context.report({ node, message: 避免使用oldVar作为变量名 }); } } }; } };6. 疑难问题解决问题1ESLint在Vue模板中不生效解决方案确保安装了eslint-plugin-vue并检查.eslintrc.js中的extends包含plugin:vue/recommended问题2保存时修复部分规则无效可能原因某些规则需要手动修复如复杂度检查调试方法运行eslint --fix src/查看完整输出问题3与Prettier规则冲突典型表现缩进被反复修改终极方案使用eslint-config-prettier禁用所有冲突规则我在实际项目中遇到最棘手的问题是SSR项目的服务端代码检查最终通过这样的配置解决overrides: [ { files: [**/server/**/*.js], env: { node: true }, rules: { no-console: off, import/no-extraneous-dependencies: [error, { devDependencies: true }] } } ]