19.1 ESLint + Prettier + Stylelint 代码质量与格式统一

代码风格不统一、潜在 bug 靠肉眼检查、样式文件缺乏约束——这些问题在多人协作的中后期会集中爆发，而 ESLint、Prettier、Stylelint 这三件套能把绝大多数格式和规范问题在提交前自动拦截下来。

三者分别干什么

ESLint：负责 JavaScript/TypeScript 的代码质量与风格规则。它既能揪出 const 被重复声明这种潜在错误，也能约束你统一使用单引号、禁止 var、要求组件名使用多词。
Prettier：纯粹的代码格式化工具，不关心逻辑是否错误，只关心缩进、换行、尾逗号、分号这些视觉格式。它的核心理念是“停止争论格式，工具说了算”。
Stylelint：样式代码的检查工具，覆盖 CSS、SCSS、Less 以及 Vue 单文件组件中的 <style> 块。能约束属性排序、禁用 !important、警告无效的十六进制颜色等。

在 Vue 项目中，三者互为补充：ESLint 管 JS/TS 逻辑与风格，Prettier 管所有文件的格式美化，Stylelint 管样式代码。它们各司其职，避免职责重叠导致的冲突。

在 Vue 3 项目中的安装与配置

假设用 Vite 创建的项目，结构如下：

npm install -D eslint prettier stylelint
# Vue 专属的 ESLint 插件与解析器
npm install -D eslint-plugin-vue vue-eslint-parser
# TypeScript 支持（如果项目使用 TS）
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin
# Prettier 与 ESLint 的衔接，关掉冲突规则
npm install -D eslint-config-prettier eslint-plugin-prettier
# Stylelint 的 Vue 支持
npm install -D stylelint-config-standard stylelint-config-recommended-vue postcss-html

1. ESLint 配置文件 .eslintrc.cjs（Vite 默认使用 .cjs）

module.exports = {
  root: true,
  env: {
    browser: true,
    node: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended', // Vue 3 推荐规则，含组件名多词、属性顺序等
    'plugin:@typescript-eslint/recommended', // 如果使用 TS
    'prettier', // 必须放在最后，覆盖 ESLint 与 Prettier 冲突的规则
  ],
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: '@typescript-eslint/parser', // 解析 script 中的 TS
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    // 自定义规则，如：允许组件名使用单词（看团队偏好）
    'vue/multi-word-component-names': 'off',
  },
}

2. Prettier 配置文件 prettierrc.json

{
  "semi": false,        // 不使用分号
  "singleQuote": true,  // 使用单引号
  "trailingComma": "all", // 尾逗号
  "printWidth": 100,    // 折行长度
  "tabWidth": 2,
  "vueIndentScriptAndStyle": true // 缩进 script 和 style 内容
}

3. Stylelint 配置文件 stylelint.config.cjs

module.exports = {
  extends: [
    'stylelint-config-standard',            // 标准 CSS 规则
    'stylelint-config-recommended-vue',     // Vue 特定规则，支持 .vue 文件
  ],
  rules: {
    // 比如允许任意顺序的属性，或禁用某些特性
    'no-descending-specificity': null, // 关闭降序优先级检查（团队视情况）
    'selector-class-pattern': null,    // 不限制选择器命名方式（如 BEM 或驼峰）
  },
}

4. 配置 VSCode 自动修复

在 .vscode/settings.json 中设置保存时自动用工具格式化，极大提升体验：

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

为什么不直接让 Prettier 作为默认格式化器并打开 formatOnSave？因为先运行 ESLint/ Stylelint 修复（自动修改可修复的错误）再交给 Prettier 格式化，能避免 Prettier 格式化结果又违反 ESLint 规则的情况。

搭配 Husky + lint-staged 实现自动化检查

只在编辑器里提醒还不够，必须做到提交前自动检查，不通过就拒绝提交。

npm install -D husky lint-staged
npx husky install
# 添加 pre-commit 钩子
npx husky add .husky/pre-commit "npx lint-staged"

在 package.json 中配置 lint-staged：

{
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"],
    "*.{css,scss,vue}": ["stylelint --fix"],
    "*.{json,md,html}": ["prettier --write"]
  }
}

这样每次 git commit 时，只有被暂存区的文件会被检查并自动修复，不会去扫描整个项目，速度快且不干扰历史遗留代码。

落到实处：统一团队规范

最终文档应该在项目仓库里维护一个 .editorconfig、一套配置文件，并在 README 中提供安装 VSCode 插件的指引：

ESLint
Prettier
Stylelint
并建议开启 formatOnSave 与 codeActionsOnSave。

工具链搭建好之后，团队成员几乎不需要再去讨论“这里该不该加分号”“缩进几个空格”，机器会保证所有人产出的代码风格一致，代码审查真正聚焦在逻辑和架构上。