Vue 3项目中ESLint与Prettier的深度集成指南

1. 为什么我们需要 ESLint + Prettier

作为一个经历过无数次代码审查痛苦的前端开发者，我深刻体会到统一代码风格的重要性。记得去年接手一个遗留项目时，发现同一个文件里居然混杂着四种不同的缩进风格、三种引号用法，还有各种随心所欲的换行。这种代码不仅难以维护，更让团队协作变成了一场噩梦。

ESLint 和 Prettier 的组合就像是给项目请了两位专业管家：一位负责检查代码质量（ESLint），另一位负责保持代码美观（Prettier）。特别是在 Vue 3 + TypeScript + Vite 这种现代技术栈中，它们的价值更加凸显。

提示：虽然本文以 Vue 3 项目为例，但配置思路同样适用于 React、Angular 等其他框架，只需调整对应的插件即可。

2. 环境准备与核心依赖安装

2.1 创建项目基础

首先确保你已经初始化了一个 Vite + Vue 3 + TypeScript 项目。如果还没有，可以运行：

bash复制npm create vite@latest my-project --template vue-ts

2.2 安装 ESLint 全家桶

现代前端项目建议使用 ESLint 的扁平化配置（Flat Config），这是 ESLint 未来的发展方向。安装以下核心依赖：

bash复制npm install -D eslint @eslint/js

接着安装 Vue 和 TypeScript 支持插件：

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

2.3 集成 Prettier

为了让 ESLint 和 Prettier 和谐共处，需要安装集成插件：

bash复制npm install -D eslint-config-prettier eslint-plugin-prettier prettier

这里有个常见误区：很多人会同时安装 eslint-plugin-prettier 和 prettier-eslint，其实只需要前者就够了。后者是另一种集成方式，容易造成混淆。

3. 深度配置 ESLint

3.1 创建 ESLint 配置文件

在项目根目录创建 eslint.config.js（注意不是传统的 .eslintrc.js）：

javascript复制import js from '@eslint/js';
import prettierConfig from 'eslint-config-prettier';
import prettierPlugin from 'eslint-plugin-prettier';
import globals from 'globals';
import vue from 'eslint-plugin-vue';
import vueTsConfig from '@vue/eslint-config-typescript';
import tseslint from '@typescript-eslint/eslint-plugin';

export default [
  // 排除不需要检查的文件
  {
    ignores: ['node_modules/', 'dist/', 'vite.config.*', '.prettierrc.cjs', 'prettier.config.cjs'],
  },
  
  // 基础 JS 规则
  js.configs.recommended,
  
  // 禁用与 Prettier 冲突的 ESLint 规则（必须放在 vue/ts 规则前）
  prettierConfig,
  
  // Vue 3 核心规则
  ...vue.configs['flat/essential'],
  ...vue.configs['flat/strongly-recommended'],
  ...vue.configs['flat/recommended'],
  
  // Vue + TS 整合规则
  ...vueTsConfig(),
  
  {
    files: ['**/*.{js,jsx,ts,tsx,vue}'],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
        defineProps: 'readonly',
        defineEmits: 'readonly',
        defineExpose: 'readonly',
        withDefaults: 'readonly',
      },
      ecmaVersion: 'latest',
      sourceType: 'module',
    },
    plugins: {
      prettier: prettierPlugin,
      '@typescript-eslint': tseslint,
    },
    rules: {
      'prettier/prettier': 'error',
      
      // Vue 专属规则
      'vue/multi-word-component-names': 'off',
      'vue/no-unused-vars': 'error',
      'vue/no-v-html': 'warn',
      
      // TS 专属规则
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/ban-ts-comment': 'warn',
      
      // 通用规则
      'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
      'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
      'no-undef': 'off',
    },
  },
];

3.2 关键配置解析

1. 规则优先级：eslint-config-prettier 必须放在 Vue 和 TS 规则之前，这样才能正确禁用冲突的格式规则。

2. Vue 宏函数处理：Vue 3 的 defineProps 等宏函数需要声明为全局变量，否则 ESLint 会报未定义错误。

3. 环境区分：生产环境禁用 console 和 debugger，开发环境则相对宽松。

4. 渐进式采用：像 no-explicit-any 这样的严格规则先设为警告，给团队适应时间。

4. Prettier 配置详解

4.1 创建 Prettier 配置文件

在项目根目录创建 prettier.config.cjs：

javascript复制module.exports = {
  printWidth: 120,
  tabWidth: 2,
  useTabs: false,
  singleQuote: true,
  semi: true,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'avoid',
  endOfLine: 'lf',
  vueIndentScriptAndStyle: true,
  singleAttributePerLine: false
};

4.2 配置项最佳实践

1. printWidth：Vue 单文件组件建议设为 100-120，比纯 JS 项目稍大。

2. vueIndentScriptAndStyle：确保 <script> 和 <style> 内的代码也能正确缩进。

3. singleAttributePerLine：Vue 3 的长属性建议保持单行，提高可读性。

4.3 创建忽略文件

添加 .prettierignore：

code复制node_modules/
dist/
.eslint.config.js
.prettierrc.js
vite.config.ts
*.md
*.json
public/

5. 开发环境集成

5.1 VSCode 终极配置

在项目 .vscode/settings.json 中添加：

json复制{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue"
  ],
  "typescript.tsdk": "node_modules/typescript/lib"
}

5.2 添加实用脚本

在 package.json 中添加：

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

6. 实战经验与避坑指南

6.1 常见问题解决

1. 配置文件格式问题：

   • 在 ESM 项目中，配置文件要用 .cjs 后缀
   • 如果遇到 require 错误，检查文件扩展名和 package.json 的 type 字段

2. 规则冲突：

   • 确保 eslint-config-prettier 放在其他配置之前
   • 如果 Prettier 和 ESLint 还在打架，可以运行 npx eslint-config-prettier-check

3. Vue 文件格式化问题：

   • 确保安装了 prettier-plugin-vue
   • 检查 vueIndentScriptAndStyle 配置

6.2 性能优化技巧

1. 增量检查：只检查变动的文件

   bash复制eslint --cache --fix
   

2. 限制检查范围：配合 git diff 只检查修改的文件

   bash复制eslint $(git diff --name-only HEAD | grep '\.vue$')
   

3. 禁用不必要的规则：大型项目可以暂时关闭耗时的规则如 import/no-cycle

7. 团队协作策略

7.1 渐进式采用路线

1. 第一阶段：只启用最基本的规则（语法错误、明显问题）
2. 第二阶段：添加代码质量规则（未使用变量、any 类型等）
3. 第三阶段：启用风格规则（引号、缩进等）

7.2 Git 钩子集成

安装 husky 和 lint-staged：

bash复制npm install -D husky lint-staged

在 package.json 中添加：

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

设置 pre-commit 钩子：

bash复制npx husky add .husky/pre-commit "npx lint-staged"

8. 高级定制技巧

8.1 自定义规则优先级

在 eslint.config.js 中，后面的规则会覆盖前面的。利用这个特性可以实现：

javascript复制{
  rules: {
    // 项目通用规则
    '@typescript-eslint/no-explicit-any': 'warn'
  }
},
{
  files: ['src/utils/*.ts'],
  rules: {
    // 工具函数更严格
    '@typescript-eslint/no-explicit-any': 'error'
  }
}

8.2 动态规则配置

根据环境变量调整规则严格程度：

javascript复制const isStrictMode = process.env.LINT_STRICT === 'true';

rules: {
  '@typescript-eslint/no-explicit-any': isStrictMode ? 'error' : 'warn'
}

8.3 共享配置方案

大型项目可以提取公共配置：

javascript复制// eslint-config-shared.js
export const baseConfig = {
  rules: {
    // 公共规则
  }
};

// 项目中的 eslint.config.js
import { baseConfig } from 'eslint-config-shared';
export default [...baseConfig];

9. 效果展示与指标监控

9.1 控制台输出示例

成功配置后，运行 npm run lint 应该看到类似输出：

code复制/src/components/HelloWorld.vue
  15:5  warning  Unexpected console statement  no-console
  22:3  error    Missing return type on function  @typescript-eslint/explicit-function-return-type

✖ 2 problems (1 error, 1 warning)

9.2 与 CI/CD 集成

在 GitHub Actions 中添加 lint 检查：

yaml复制name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run lint

9.3 质量指标跟踪

使用 ESLint 的 --format 选项生成报告：

bash复制eslint . --format json --output-file eslint-report.json

然后可以用工具分析错误趋势，逐步提高代码质量。

10. 维护与升级策略

10.1 定期更新依赖

至少每季度更新一次 ESLint 和 Prettier 相关依赖：

bash复制npm outdated
npm update eslint @eslint/js eslint-plugin-vue @typescript-eslint/eslint-plugin prettier

10.2 规则迭代流程

1. 在开发分支测试新规则
2. 使用 --fix 自动修复可修复的问题
3. 评估剩余问题的影响范围
4. 团队讨论后决定是否采纳

10.3 文档化定制规则

为每个自定义规则添加注释说明：

javascript复制rules: {
  // 允许单单词组件名，因为我们的业务组件有大量简单展示组件
  'vue/multi-word-component-names': 'off'
}

11. 备选方案评估

虽然 ESLint + Prettier 是主流选择，但了解其他方案也很重要：

12. 疑难问题排查手册

12.1 ESLint 不生效检查清单

1. 确认文件在 eslint.config.js 的 files 模式匹配范围内
2. 检查 VSCode 的 ESLint 插件是否启用
3. 查看 ESLint 输出日志：ESLint: Output 面板
4. 尝试命令行直接运行：npx eslint your-file.vue

12.2 Prettier 格式化异常处理

1. 确认没有其他格式化插件冲突
2. 检查文件是否在 .prettierignore 中
3. 尝试直接运行：npx prettier --write your-file.vue
4. 检查 editor.defaultFormatter 设置

12.3 性能问题优化

如果 lint 速度慢：

1. 使用 --cache 选项
2. 减少不必要的文件检查范围
3. 禁用耗时的规则如 import/no-cycle
4. 考虑使用 eslint-plugin-prettier 的 prettier --check 替代方案

13. 真实项目配置示例

以下是一个大型后台管理系统实际使用的配置：

javascript复制// eslint.config.js
import js from '@eslint/js';
import prettierConfig from 'eslint-config-prettier';
import globals from 'globals';
import vue from 'eslint-plugin-vue';
import tseslint from '@typescript-eslint/eslint-plugin';

const isCI = process.env.CI === 'true';

export default [
  {
    ignores: ['**/dist/**', '**/coverage/**', '**/cypress/**'],
  },
  js.configs.recommended,
  prettierConfig,
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.ts', '**/*.vue'],
    plugins: {
      '@typescript-eslint': tseslint,
    },
    languageOptions: {
      parserOptions: {
        project: './tsconfig.json',
      },
    },
    rules: {
      '@typescript-eslint/interface-name-prefix': 'off',
      '@typescript-eslint/explicit-function-return-type': 'off',
      '@typescript-eslint/no-floating-promises': isCI ? 'error' : 'warn',
    },
  },
  {
    files: ['**/src/utils/**'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
    },
  },
];

14. 未来演进方向

随着前端工具链的发展，ESLint 和 Prettier 也在不断进化：

1. Flat Config 全面普及：ESLint 正在逐步淘汰传统配置方式
2. 更快的执行引擎：如 Biome 等 Rust 实现的工具开始出现
3. 更智能的自动修复：基于 AI 的代码修复方案正在兴起
4. 一体化工具链：Volar 等工具开始集成 lint 功能

不过目前来看，ESLint + Prettier 的组合在未来几年仍会是主流选择。