一、前言

做 Vue3 + Vite 大型项目时，代码规范、统一格式化、自动纠错是刚需，多人协作更需要统一编码风格。但新版 create-vue 生成的项目用的是 ESLint 扁平配置（eslint.config.js），和旧版 .eslintrc 写法完全不一样，很多同学配置完规则不生效、保存不自动修复、依赖安装报错、VS Code 设置爆红等一堆坑。

今天把从零配置完整流程、每一步操作、常见报错问题 + 解决方案整理成可直接照搬的教程，新手也能一次配置成功。

---

二、整体配置流程

1. 创建 Vue3 + Vite 项目

使用官方脚手架创建项目：

bash

运行

npm create vue@latest

创建选项建议（大项目标配）：

• TypeScript：按需选择
• JSX：否
• Vue Router：是
• Pinia：是
• ESLint：是
• Prettier：先不选，后续手动集成
• 单元测试 / 端测：否
• 是否引入示例代码：选 Yes，清空示例空白项目，适合大项目从零架构

---

2. 安装 Prettier 相关依赖

项目自带 ESLint，但没有 Prettier 格式化插件，必须手动安装：

运行

# 清理 npm 缓存（解决安装报错）
npm cache clean --force

# 用 pnpm 安装（推荐，稳定不报错）
pnpm add prettier eslint-plugin-prettier -D

---

3. 改写新版 ESLint 配置文件

项目根目录 eslint.config.js 为新版扁平配置，直接替换完整配置，集成自定义代码规范规则、Prettier 格式化、Vue 规则校验。

完整可用配置：

import { defineConfig, globalIgnores } from 'eslint/config'
import globals from 'globals'
import js from '@eslint/js'
import pluginVue from 'eslint-plugin-vue'
import pluginOxlint from 'eslint-plugin-oxlint'
import prettier from 'eslint-plugin-prettier'
import skipFormatting from 'eslint-config-prettier/flat'

export default defineConfig([
  {
    name: 'app/files-to-lint',
    files: ['**/*.{vue,js,mjs,jsx}'],
  },

  globalIgnores(['**/dist/**', '**/dist-ssr/**', '**/coverage/**']),

  {
    languageOptions: {
      globals: {
        ...globals.browser,
      },
    },
  },

  js.configs.recommended,
  ...pluginVue.configs['flat/essential'],
  ...pluginOxlint.buildFromOxlintConfigFile('.oxlintrc.json'),
  skipFormatting,

  {
    plugins: {
      prettier,
    },
    rules: {
      // Prettier 格式化规则
      'prettier/prettier': [
        'warn',
        {
          singleQuote: true,
          semi: false,
          printWidth: 80,
          trailingComma: 'none',
          endOfLine: 'auto'
        }
      ],
      // Vue 组件命名规则
      'vue/multi-word-component-names': [
        'warn',
        { ignores: ['index'] }
      ],
      // 关闭 setup props 解构校验
      'vue/no-setup-props-destructure': 'off',
      // 未定义变量直接报错
      'no-undef': 'error'
    }
  }
])

---

4. VS Code 编辑器关键配置

打开 VS Code settings.json，配置保存自动修复、识别 vue/js 文件、关闭自带格式化冲突：

json

{
  "workbench.colorTheme": "One Dark Pro",
  "workbench.iconTheme": "material-icon-theme",
  "files.autoSave": "afterDelay",
  "editor.fontSize": 20,
  "editor.wordWrap": "on",
  "editor.formatOnPaste": true,
  // 关闭全局自动格式化，交给 ESLint 接管
  "editor.formatOnSave": false,
  "explorer.confirmDragAndDrop": false,
  "emmet.triggerExpansionOnTab": true,
  // 保存自动执行 ESLint 修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  // 让 ESLint 校验 vue、js 等文件
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue"
  ]
}

---

5. 重启 ESLint 服务生效

修改完配置必须重启，否则规则不生效：

1. 按 Ctrl + Shift + P
2. 输入：ESLint: Restart ESLint Server
3. 重启后随便写代码测试：双引号、未定义变量看是否提示、保存是否自动修复。

---

6. 进阶：集成 Husky + lint-staged（提交代码强制规范）

适合团队大项目，提交代码前自动校验修复：

1. 初始化 husky

运行

pnpm dlx husky-init && pnpm install

1. 安装 lint-staged

运行

pnpm i lint-staged -D

1. 在 package.json 添加配置

json

"lint-staged": {
  "*.{js,ts,vue}": [
    "eslint --fix"
  ]
},
"scripts": {
  "lint-staged": "lint-staged"
}

1. 配置 git 提交钩子，提交前自动执行代码校验修复。

---

三、配置过程常见问题 + 解决方案

问题 1：npm 安装依赖报错 Cannot read properties of null (reading 'matches')

原因：npm 缓存损坏、版本老旧、环境异常。解决办法：

1. 清理 npm 缓存：npm cache clean --force
2. 改用 pnpm 安装依赖，稳定性远超 npm
3. 实在不行升级 npm：npm install -g npm@latest

---

问题 2：ESLint 添加自定义规则后完全不生效，无报错、不提示

原因：

1. 新版扁平配置没导入 prettier 插件，也没在 plugins 注册
2. 只写了 rules，缺少插件声明，ESLint 不识别 prettier 规则
3. 没重启 ESLint 服务，配置未加载

解决办法：

1. 配置顶部必须导入 import prettier from 'eslint-plugin-prettier'
2. rules 同级添加 plugins: { prettier }
3. 每次改完 eslint.config.js 都重启 ESLint 服务

---

问题 3：保存文件不自动格式化、不修复代码规范

原因：

1. VS Code 没开启保存自动执行 ESLint 修复
2. 开了 editor.formatOnSave 和 ESLint 冲突
3. 没配置 eslint.validate 识别 .vue 文件

解决办法：

1. 设置 editor.formatOnSave: false 关闭自带格式化
2. 加上 editor.codeActionsOnSave 配置
3. 配置 eslint.validate 包含 vue、js、ts

---

问题 4：VS Code 配置 editor.codeActionsOnSave 爆红报错

原因：新版 VS Code 不再支持 true/false 布尔值写法。解决办法：把旧写法

json

"source.fixAll.eslint": true

改成新版标准：

json

"source.fixAll.eslint": "explicit"

---

问题 5：Vue 组件命名、props 解构规则不生效

原因：用了旧版 ESLint 配置写法，和新版扁平结构不兼容。解决办法：直接复制本文完整的 eslint.config.js，不要自己零散拼接配置。

---

四、总结

1. Vue3 + Vite 新项目默认是 ESLint 扁平配置，和旧版语法不同，不能照搬老项目配置；
2. Prettier 必须手动装依赖、手动导入插件并注册，否则规则完全无效；
3. VS Code 三件套：关闭自带保存格式化、开启 ESLint 保存自动修复、配置文件类型校验；
4. 所有配置修改后 必须重启 ESLint 服务，否则不生效；
5. 大项目建议搭配 Husky + lint-staged，实现团队代码提交强制规范，避免烂代码入库。

---

💡 补充：如果配置后还是有问题，可以直接删除 node_modules 和 pnpm-lock.yaml，重新运行 pnpm install 解决依赖缓存问题。