Vue3+TypeScript项目ESLint与Prettier配置指南-代码聚汇网

Vue3+TypeScript项目ESLint与Prettier配置指南

蝨孨槑黽

1. 为什么Vue3+TypeScript项目需要ESLint和Prettier

在开始配置之前，我们先搞清楚为什么现代前端项目都需要这两样工具。我接手过不少遗留项目，发现一个规律：没有代码规范约束的项目，经过3-6个月迭代后，代码风格就会变得五花八门。有的同事喜欢加分号，有的不加；有的用双引号，有的用单引号；缩进有2空格、4空格甚至tab键混用的情况。这种风格混乱会导致：

代码合并冲突增加：无关格式修改会干扰真正的代码变更
可读性下降：团队成员需要不断适应不同风格
隐性bug风险：不规范的代码可能隐藏类型错误或语法陷阱

ESLint和Prettier的组合正好解决了这些问题：

ESLint：负责代码质量检查，比如变量未使用、错误的类型定义、不安全的语法等
Prettier：专注代码格式化，统一缩进、引号、换行等风格问题

提示：Vue3+TypeScript项目尤其需要这套工具链，因为组合式API的灵活性加上TS类型系统，没有静态检查很容易写出运行时才会暴露的问题。

2. 环境准备与依赖安装

2.1 项目基础要求

在开始前确保你的项目满足：

使用Vue3（Options API或Composition API均可）
已集成TypeScript（有tsconfig.json）
基于Vite或Webpack构建（本文配置通用）

2.2 安装核心依赖

打开终端，在项目根目录执行：

bash复制npm install eslint prettier eslint-plugin-vue @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-prettier -D

这里解释下每个包的作用：

依赖包	用途	必选
eslint	代码检查核心	✅
prettier	代码格式化核心	✅
eslint-plugin-vue	Vue语法规则支持	✅
@typescript-eslint/eslint-plugin	TS语法规则	✅
@typescript-eslint/parser	TS语法解析器	✅
eslint-config-prettier	解决ESLint与Prettier规则冲突	✅
eslint-plugin-prettier	将Prettier作为ESLint规则运行	✅

注意：所有依赖都安装为开发依赖(-D)，因为这只是开发阶段的工具链。

3. 配置文件详解

3.1 ESLint核心配置(.eslintrc.cjs)

在项目根目录创建.eslintrc.cjs（注意后缀是cjs）：

javascript复制module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  parser: 'vue-eslint-parser',
  parserOptions: {
    ecmaVersion: 'latest',
    parser: '@typescript-eslint/parser',
    sourceType: 'module',
    extraFileExtensions: ['.vue']
  },
  extends: [
    'plugin:vue/vue3-essential',
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended'
  ],
  rules: {
    // 开发环境允许console
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    // TypeScript相关规则
    '@typescript-eslint/no-explicit-any': 'off',
    '@typescript-eslint/explicit-module-boundary-types': 'off',
    // Vue相关规则  
    'vue/multi-word-component-names': 'off',
    // Prettier整合
    'prettier/prettier': [
      'error',
      {
        endOfLine: 'auto'
      }
    ]
  }
}

关键配置说明：

parser：使用vue-eslint-parser解析.vue文件
parserOptions：指定TS解析器和额外文件扩展
extends：继承Vue3、TS和Prettier的推荐规则集
rules：自定义规则覆盖，这里关闭了一些严格限制

3.2 ESLint忽略文件(.eslintignore)

创建.eslintignore避免检查无关文件：

code复制node_modules/
dist/
*.config.js
*.config.cjs
public/
*.log
temp/

3.3 Prettier配置(.prettierrc.cjs)

创建.prettierrc.cjs定义格式化规则：

javascript复制module.exports = {
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: true,
  quoteProps: 'as-needed',
  jsxSingleQuote: false,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'avoid',
  endOfLine: 'lf',
  vueIndentScriptAndStyle: false
}

推荐配置说明：

singleQuote: true：统一使用单引号
trailingComma: 'es5'：对象/数组多行时添加尾逗号
arrowParens: 'avoid'：箭头函数单参数省略括号

3.4 Prettier忽略文件(.prettierignore)

创建.prettierignore继承ESLint的忽略规则：

code复制.eslintignore
node_modules/
dist/
public/

4. 集成到开发工作流

4.1 添加npm脚本

在package.json的scripts中添加：

json复制{
  "scripts": {
    "lint": "eslint . --ext .vue,.js,.ts,.jsx,.tsx",
    "lint:fix": "eslint . --ext .vue,.js,.ts,.jsx,.tsx --fix",
    "format": "prettier --write \"**/*.{vue,js,ts,jsx,tsx,json,css,scss,md}\""
  }
}

使用方法：

npm run lint：检查代码问题
npm run lint:fix：自动修复可修复的问题
npm run format：格式化所有文件

4.2 VSCode集成（强烈推荐）

安装插件：
- ESLint (Dirk Baeumer)
- Prettier - Code formatter
配置settings.json：

json复制{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "eslint.validate": [
    "javascript",
    "typescript",
    "vue"
  ],
  "prettier.disableLanguages": ["markdown"]
}

这样配置后：

保存文件时自动格式化
编辑时实时显示ESLint错误
Vue文件也能正确应用规则

5. 常见问题与解决方案

5.1 解析错误：Parsing error

现象：在.vue文件中出现解析错误

解决：

确保安装了vue-eslint-parser
检查.eslintrc中的parser配置是否正确
确保parserOptions中有extraFileExtensions: ['.vue']

5.2 Prettier与ESLint规则冲突

现象：格式化后ESLint报错

解决：

确保extends中包含plugin:prettier/recommended
检查eslint-config-prettier是否安装
规则冲突时优先采用Prettier的规则

5.3 保存时无法自动修复

排查步骤：

检查VSCode的ESLint插件是否启用
查看输出面板中ESLint的日志
确保文件类型在eslint.validate列表中

5.4 TypeScript类型规则报错

典型场景：@typescript-eslint开头的规则报错

调整方案：

javascript复制rules: {
  '@typescript-eslint/no-unused-vars': 'warn',
  '@typescript-eslint/no-empty-function': 'off'
}

6. 高级配置技巧

6.1 针对不同文件类型设置规则

在.eslintrc.cjs中添加overrides：

javascript复制{
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      rules: {
        '@typescript-eslint/explicit-function-return-type': 'error'
      }
    },
    {
      files: ['*.vue'],
      rules: {
        'vue/require-default-prop': 'error'
      }
    }
  ]
}

6.2 与Git Hooks集成

安装husky和lint-staged：

bash复制npm install husky lint-staged -D

在package.json中添加：

json复制{
  "lint-staged": {
    "*.{vue,js,ts}": "eslint --fix",
    "*.{vue,js,ts,css,md}": "prettier --write"
  }
}

6.3 团队共享配置

创建独立的配置包：

新建npm包包含.eslintrc和.prettierrc
发布到私有仓库或npm
项目中安装后extends该配置

javascript复制// 项目中的.eslintrc.cjs
module.exports = {
  extends: '@your-team/eslint-config-vue-ts'
}

这套配置已经在多个Vue3+TypeScript项目中验证过，能有效提升代码质量和团队协作效率。刚开始可能会觉得规则限制太多，但坚持2周后就会感受到其价值——特别是当需要修改半年前写的代码时，统一的风格会让你感谢当初的决定。