Vue3项目ESLint+Prettier代码规范配置指南

发布时间：2026/10/31 22:01:32
Vue3项目ESLint+Prettier代码规范配置指南

1. 项目背景与目标

这个系列教程的第三部分将重点解决Vue3项目中的代码规范问题。作为现代前端开发的标准配置，ESLint和Prettier的组合能够显著提升团队协作效率。Vite作为新一代构建工具，与TypeScript的结合更是如虎添翼。

在实际开发中，我们经常会遇到这样的场景：不同开发者提交的代码风格各异，有的用单引号有的用双引号；有的喜欢加分号有的不加；缩进有用2空格有用4空格的。这种风格不统一会导致代码库看起来杂乱无章，增加维护成本。而通过ESLint+Prettier的组合，我们可以实现：

  • 自动格式化代码，统一团队代码风格
  • 静态代码分析，提前发现潜在错误
  • 类型检查，减少运行时错误
  • 保存时自动修复，提升开发效率

2. 环境准备与项目初始化

2.1 创建Vite项目

首先确保你的开发环境已经安装了Node.js（建议版本16+）和pnpm（比npm/yarn更快的包管理器）。打开终端，执行以下命令创建项目：

pnpm create vite@latest vue3-admin --template vue-ts

这个命令会创建一个基于Vue3和TypeScript的Vite项目。创建完成后，进入项目目录并安装基础依赖：

cd vue3-admin pnpm install

2.2 项目结构分析

初始化后的项目结构如下：

vue3-admin/ ├── public/ # 静态资源 ├── src/ # 源代码 │ ├── assets/ # 资源文件 │ ├── components/ # 组件 │ ├── App.vue # 根组件 │ └── main.ts # 入口文件 ├── index.html # 主页面 ├── package.json # 项目配置 ├── tsconfig.json # TypeScript配置 └── vite.config.ts # Vite配置

3. ESLint配置详解

3.1 安装与初始化ESLint

执行以下命令初始化ESLint：

pnpx eslint --init

在初始化过程中，我们需要做出以下选择：

  1. 检查语法和发现问题
  2. 使用ES模块
  3. 选择Vue.js框架
  4. 使用TypeScript
  5. 运行在浏览器和Node环境
  6. 配置文件格式选择TypeScript
  7. 安装jiti（用于低版本Node读取TS配置）

初始化完成后，项目会新增eslint.config.ts文件和一系列依赖。

3.2 配置文件解析

打开eslint.config.ts，我们可以看到基础配置：

import js from "@eslint/js"; import globals from "globals"; import tseslint from "typescript-eslint"; import pluginVue from "eslint-plugin-vue"; import { defineConfig } from "eslint/config"; export default defineConfig([ { files: ["**/*.{js,mjs,cjs,ts,mts,cts,vue}"], plugins: { js }, extends: ["js/recommended"], languageOptions: { globals: { ...globals.browser, ...globals.node } }, rules: { semi: ["warn", "always"], }, }, tseslint.configs.recommended, pluginVue.configs["flat/essential"], { files: ["**/*.vue"], languageOptions: { parserOptions: { parser: tseslint.parser } }, }, ]);

这个配置做了以下几件事：

  1. 设置检查的文件类型
  2. 启用ESLint的JS核心规则
  3. 配置浏览器和Node的全局变量
  4. 添加TypeScript支持
  5. 添加Vue文件支持
  6. 设置基础规则（如强制分号）

3.3 添加脚本命令

在package.json中添加以下脚本：

"scripts": { "lint": "eslint . --ext .vue,.js,.ts", "lint:fix": "eslint . --ext .vue,.js,.ts --fix" }

现在可以运行以下命令检查或修复代码：

pnpm lint # 检查代码 pnpm lint:fix # 自动修复可修复的问题

4. Prettier集成

4.1 安装依赖

Prettier负责代码格式化，与ESLint配合使用：

pnpm add prettier eslint-config-prettier eslint-plugin-prettier -D

这三个包的作用分别是：

  • prettier: 核心格式化工具
  • eslint-config-prettier: 关闭与Prettier冲突的ESLint规则
  • eslint-plugin-prettier: 将Prettier作为ESLint规则运行

4.2 修改ESLint配置

更新eslint.config.ts，添加Prettier相关配置：

import eslintConfigPrettier from "eslint-config-prettier/flat"; import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended"; export default defineConfig([ // ...原有配置 eslintConfigPrettier, eslintPluginPrettierRecommended, ]);

重要提示：Prettier配置必须放在最后，因为它会覆盖前面的格式相关规则

4.3 配置Prettier规则

在项目根目录创建.prettierrc文件：

{ "printWidth": 120, "tabWidth": 2, "useTabs": false, "semi": true, "singleQuote": true, "quoteProps": "as-needed", "jsxSingleQuote": false, "trailingComma": "es5", "bracketSpacing": true, "bracketSameLine": false, "arrowParens": "always", "vueIndentScriptAndStyle": true, "endOfLine": "lf" }

这些规则的含义：

  • printWidth: 每行最大120字符
  • tabWidth: 2空格缩进
  • singleQuote: 使用单引号
  • trailingComma: 多行时保留尾随逗号
  • vueIndentScriptAndStyle: Vue文件中script和style内容缩进

5. VSCode集成

5.1 安装必要插件

在VSCode中安装以下插件：

  • ESLint
  • Prettier - Code formatter
  • Volar (Vue语言支持)

5.2 配置自动格式化

在VSCode设置中(settings.json)添加：

{ "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true, "eslint.validate": ["javascript", "typescript", "vue"], "editor.codeActionsOnSave": { "source.fixAll.eslint": true } }

这样配置后，保存文件时会：

  1. 自动运行ESLint修复
  2. 自动用Prettier格式化代码

6. 常见问题与解决方案

6.1 ESLint无法识别Vue文件

如果遇到Vue文件不被ESLint识别的问题，检查：

  1. 确保安装了eslint-plugin-vue
  2. 检查eslint.config.ts中Vue相关配置是否正确
  3. 确保VSCode的ESLint插件已启用

6.2 Prettier与ESLint规则冲突

常见的冲突包括：

  • 引号规则
  • 分号规则
  • 缩进规则

解决方案：

  1. 确保eslint-config-prettier正确配置
  2. 检查配置顺序（Prettier配置必须在最后）
  3. 统一.prettierrc和ESLint规则

6.3 保存时无法自动修复

如果保存时没有自动修复，检查：

  1. VSCode的ESLint插件是否安装并启用
  2. 工作区是否正确识别了项目根目录的ESLint配置
  3. 检查settings.json中的配置是否正确

7. 高级配置技巧

7.1 自定义规则

在eslint.config.ts中可以添加自定义规则，例如：

rules: { 'vue/multi-word-component-names': 'off', // 关闭组件名必须多单词的要求 '@typescript-eslint/no-explicit-any': 'warn', // 使用any时警告 'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off' // 生产环境禁止console }

7.2 Git Hooks集成

可以通过Husky在提交前自动检查代码：

  1. 安装Husky：
pnpm add husky -D npx husky install
  1. 添加pre-commit钩子：
npx husky add .husky/pre-commit "pnpm lint"

这样在每次git commit前都会自动运行lint检查。

7.3 忽略特定文件

创建.eslintignore文件来忽略不需要检查的文件：

**/*.min.js dist/ node_modules/

8. 项目实战建议

在实际的后台管理系统开发中，建议：

  1. 组件规范：

    • 组件目录按功能划分
    • 组件名使用大驼峰命名
    • 一个组件一个目录，包含.vue文件、样式和测试

  2. TypeScript最佳实践：

    • 为所有props定义类型
    • 避免使用any类型
    • 为API响应定义接口

  3. 目录结构优化：

src/ ├── api/ # API请求 ├── assets/ # 静态资源 ├── components/ # 公共组件 ├── composables/ # 组合式函数 ├── router/ # 路由配置 ├── stores/ # Pinia状态管理 ├── styles/ # 全局样式 ├── types/ # 类型定义 ├── utils/ # 工具函数 ├── views/ # 页面组件 ├── App.vue └── main.ts
  1. 性能优化：
    • 按需加载路由组件
    • 使用Vite的代码分割
    • 合理使用keep-alive缓存组件

这套配置已经在多个实际项目中验证过，能够显著提升开发效率和代码质量。特别是在团队协作中，统一的代码风格可以减少很多不必要的争论和代码审查时间。