最新2025vue3集成ESLint+Prettier+StyleLint+LintStaged+CommitLInt

514 阅读12分钟

前言

如何基于 Vite 的 Vue3 项目中集成完整的代码规范工具链,包括:

  • ESLint - JavaScript/TypeScript 代码语法检查
  • Prettier - 代码风格格式化
  • StyleLint - CSS/SCSS 样式语法检查
  • Husky:Git 钩子管理
  • LintStaged - Git 暂存区文件检查
  • CommitLint - Git 提交信息规范检查
前置知识Vscode需要安装ESLint + Stylelint + Prettier- Code formatter插件结合使用

image.png image.png

image.png

用 Vite 创建 Vue 项目
# 使用 npm
npm create vite@latest my-vue-app -- --template vue

# 使用 pnpm
pnpm create vite my-vue-app --template vue

# 使用 yarn
yarn create vite my-vue-app --template vue
安装依赖并运行
cd my-vue-app
npm install
npm run dev

image.png

配置 ESLint
安装eslint
pnpm install -D eslint @eslint/create-config
生成 ESLint 配置文件模板
npx eslint --init
# 会出现如下选择

# 选择2
How would you like to use ESLint?
1.只检查语法
2.检查语法并提示问题

# 你的项目用的哪一种模块化方式 选择1
What type of modules does your project use?
1.JavaScript mouules(ES6)
2.CommonJS
3.None

# 使用的框架 选择2
Which framework does your project use?
1.React
2.Vue.js
3.None

# 项目是否使用TS no
Does your project use TypeScript?

# 项目在哪里跑的 选择1
Where does your code run?
1.browser
2.node

# 是否立即安装需要的依赖
Would you like to install them now?
# 会帮我们安装如下插件
# pnpm install -D @eslint/js eslint-plugin-vue globals

# 项目用哪种包管理工具 我选择pnpm
Which package manager do you want to use?
1.npm
2.yarn
3.pnpm
4.bun

**之后会生成eslint.config.js文件**  

下面是常用的eslint.config.js配置规则,更多配置规则请查阅ESLint中文
单独的语法配置需要在rules中编写,全部配置请参考:List of available rules - ESLint中文

/**
 * ESLint 扁平化配置文件 (Flat Config)
 * 用于配置 Vue + JavaScript/TypeScript 项目的代码规范检查规则
 */
import { defineConfig } from 'eslint/config'; // ESLint 配置定义工具
import globals from 'globals'; // 全局变量定义(如 browser/node 环境变量)
import js from '@eslint/js'; // ESLint 官方核心规则集
import pluginVue from 'eslint-plugin-vue'; // Vue 单文件组件专用规则插件

// 使用 defineConfig 定义配置(提供类型提示)
export default defineConfig([
    // 1. 指定应用文件范围:所有 JS 和 Vue 文件
    {
        files: ['**/*.{js,mjs,cjs,vue}']
    },

    // 2. 配置语言环境:注入浏览器全局变量(如 window, document)
    {
        files: ['**/*.{js,mjs,cjs,vue}'],
        languageOptions: {
            globals: globals.browser // 合并浏览器环境全局变量
        }
    },

    // 3. 应用 ESLint 官方推荐规则
    {
        files: ['**/*.{js,mjs,cjs,vue}'],
        plugins: { js }, // 注册 @eslint/js 插件
        extends: ['js/recommended'] // 启用推荐规则集
    },

    // 4. 启用 Vue 3 基础规则集(来自 eslint-plugin-vue)
    pluginVue.configs['flat/essential'], // 检查模板语法、组件规范等

    // 自定义规则覆盖
    {
      rules: {
          semi: ['error', 'always'], // 强制语句末尾使用分号
          indent: [
              'error',
              4,
              {
                  // 4 空格缩进
                  SwitchCase: 1 // case 子句缩进 1 级(4 空格)
              }
          ],
          '@typescript-eslint/no-unused-vars': 'off', // 关闭未使用变量检查
          '@typescript-eslint/no-var-requires': 'off', // 允许使用 require()
          '@typescript-eslint/no-explicit-any': 'off', // 允许使用 any 类型
          '@typescript-eslint/no-this-alias': 'off', // 允许 this 别名
          'no-debugger': 'off', // 允许 debugger 语句

          // ----- Vue 专用规则 -----
          'vue/multi-word-component-names': [
              // 组件名必须多单词
              'error',
              {
                  ignores: ['index', 'Header'] // 允许例外的组件名
              }
          ],
          'vue/no-unused-vars': 'off', // 关闭 Vue 未使用变量检查
          'vue/no-template-shadow': 'off', // 允许模板变量遮蔽
          'vue/require-v-for-key': 'off', // 关闭 v-for 必须带 key 的检查
          'vue/no-textarea-mustache': 'off', // 允许 textarea 使用 mustache
          'vue/no-v-html': 'off' // 允许使用 v-html(注意 XSS 风险)
      }
    }
]);

eslint.config.js 配置完成以后,需要同步配置 package.json指令用于代码质量的修复
// --cache 为仅检测改动过的代码
// --max-warnings 0 表示出现超过0个警告强制eslint以错误状态推出
"scripts": {
 "lint:eslint": "eslint --cache --max-warnings 0 {src,mock}/**/*.{js,vue,ts,tsx} --fix",
},
配置忽略文件,让 ESLint 不对这些文件进行校验

在项目根目录创建 .eslintignore: 配置文件内容如下

node_modules
*.md
.vscode
.idea
dist
/public
/docs
.husky
.local
/bin
配置Vscode代码保存Eslint自动修复

VSCode

  1. 下载ESLint插件
  2. 输入Ctrl+Shift+P打开命令面板
  3. 输入setting.json,选择Workspace Settings,生成.vscode文件

image.png

 .vscode/settings.json: 配置文件内容如下

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"  //保存时自动修复,新版推荐写法(替代 true)
  },
  "eslint.validate": ["javascript", "typescript", "vue"],  // 检查的文件类型
  "eslint.enable": true  // 启用 ESLint
}

最后定义一个未声明的变量林文强测试一下代码,保存的时候能自动缩进,还有提示代码语法错误那就可以了

image.png

配置 Prettier
安装Prettier
pnpm install -D prettier
项目根目录添加.ptettierrc.js配置文件
  • Prettier配置文件名称可以为:.ptettierrc.js、.ptettier.config.js (根据个人习惯选择即可)
  • 下面是常用的一些配置,更多配置规则大家可以前官网查看:Options · Prettier 中文网
export default {
  printWidth: 120, //单行长度
  tabWidth: 4, //缩进长度
  useTabs: false, //使用空格代替tab缩进
  semi: true, //句末使用分号
  singleQuote: true, //使用单引号
  endOfLine: "auto",
  indent: 4, //缩进长度
  trailingComma: "none", // 对象最后一个属性末尾是否要逗号
};

.ptettierrc.js 配置完成以后,需要同步配置 package.json指令用于prettier修复代码风格

{
  "script": {
    "lint:prettier": "prettier --write **/*.{js,json,tsx,css,less,scss,vue,html,md}",
  }
}
配置.prettierignore忽略文件
/dist/*
/node_modules/**
处理ESLint与Prettier规则冲突问题
安装依赖
pnpm install -D eslint-config-prettier eslint-plugin-prettier
  • eslint-config-prettier 的作用是关闭eslint中与prettier相互冲突的规则。
  • eslint-plugin-prettier 的作用是赋予eslint用prettier格式化代码的能力。 安装依赖并修改.eslintrc文件。
重新配置 ESLint
/**
 * ESLint 扁平化配置文件 (Flat Config)
 * 用于配置 Vue + JavaScript/TypeScript 项目的代码规范检查规则
 */
import { defineConfig } from 'eslint/config'; // ESLint 配置定义工具
import globals from 'globals'; // 全局变量定义(如 browser/node 环境变量)
import js from '@eslint/js'; // ESLint 官方核心规则集
import pluginVue from 'eslint-plugin-vue'; // Vue 单文件组件专用规则插件
import prettierConfig from 'eslint-config-prettier'; // 新增:Prettier 兼容配置

// 使用 defineConfig 定义配置(提供类型提示)
export default defineConfig([
    // 1. 指定应用文件范围:所有 JS 和 Vue 文件
    {
        files: ['**/*.{js,mjs,cjs,vue}']
    },

    // 2. 配置语言环境:注入浏览器全局变量(如 window, document)
    {
        files: ['**/*.{js,mjs,cjs,vue}'],
        languageOptions: {
            globals: globals.browser // 合并浏览器环境全局变量
        }
    },

    // 3. 应用 ESLint 官方推荐规则
    {
        files: ['**/*.{js,mjs,cjs,vue}'],
        plugins: { js }, // 注册 @eslint/js 插件
        extends: ['js/recommended'] // 启用推荐规则集
    },

    // 4. 启用 Vue 3 基础规则集(来自 eslint-plugin-vue)
    pluginVue.configs['flat/essential'], // 检查模板语法、组件规范等

    // 自定义规则覆盖
    {
        rules: {
            '@typescript-eslint/no-unused-vars': 'off', // 关闭未使用变量检查
            '@typescript-eslint/no-var-requires': 'off', // 允许使用 require()
            '@typescript-eslint/no-explicit-any': 'off', // 允许使用 any 类型
            '@typescript-eslint/no-this-alias': 'off', // 允许 this 别名
            'no-debugger': 'off', // 允许 debugger 语句

            // ----- Vue 专用规则 -----
            'vue/multi-word-component-names': [
                // 组件名必须多单词
                'error',
                {
                    ignores: ['index', 'Header'] // 允许例外的组件名
                }
            ],
            'vue/no-unused-vars': 'off', // 关闭 Vue 未使用变量检查
            'vue/no-template-shadow': 'off', // 允许模板变量遮蔽
            'vue/require-v-for-key': 'off', // 关闭 v-for 必须带 key 的检查
            'vue/no-textarea-mustache': 'off', // 允许 textarea 使用 mustache
            'vue/no-v-html': 'off' // 允许使用 v-html(注意 XSS 风险)
        }
    },
    prettierConfig
]);

重新配置.vscode文件
{
  "editor.formatOnSave": true, // 启用保存时自动格式化
  "editor.defaultFormatter": "esbenp.prettier-vscode", // 指定 Prettier 为默认格式化工具
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit" //保存时自动修复,新版推荐写法(替代 true)
  },
  "eslint.validate": ["javascript", "typescript", "vue"], // 检查的文件类型
  "eslint.enable": true // 启用 ESLint
}

配置StyleLint
安装依赖
pnpm install -D stylelint stylelint-config-standard

pnpm install -D stylelint-config-html stylelint-order stylelint-less postcss-html postcss-less stylelint-config-standard-vue
  • stylelint-config-standard:StyleLint 推荐配置
  • stylelint-config-prettier:关闭与 prettier 冲突的配置(StyleLint版本 > 15 可以不用配置stylelint-config-prettier)
  • stylelint-config-standard-vue:StyleLint Vue 项目推荐配置
  • postcss-html postcss-less:支持检查 less 与 html
  • stylelint-order:支持 css 样式排序
项目根目录添加.stylelintrc.js配置文件
export default {
  // 添加规则插件
  plugins: ["stylelint-order"],
  // 继承推荐规范配置
  extends: [
    "stylelint-config-standard",
    "stylelint-config-standard-vue", // 兼容 vue 文件
    //'stylelint-config-prettier', // 处理与prettier冲突,stylelint大于等于v15是已经不需要此插件
  ],
  // 不同格式的文件指定自定义语法
  overrides: [
    {
      files: ["**/*.(less|css|vue|html)"],
      customSyntax: "postcss-less",
    },
    {
      files: ["**/*.(html|vue)"],
      customSyntax: "postcss-html",
    },
  ],
  // 忽略检测文件
  ignoreFiles: [
    "**/*.js",
    "**/*.jsx",
    "**/*.tsx",
    "**/*.ts",
    "**/*.json",
    "**/*.md",
    "**/*.yaml",
  ],
  // 自定义配置规则
  rules: {
    // 便于配置变量 关闭未知属性检测
    "declaration-property-value-no-unknown": null,
    // 在 css 中使用 v-bind,不报错
    "value-keyword-case": null,
    // 关闭声明前的空行检查
    "declaration-empty-line-before": null,
    // 指定类选择器的模式
    "selector-class-pattern": null,
    // 关闭禁止值使用浏览器前缀 -webkit -moz
    "value-no-vendor-prefix": null,
    // 关闭禁止属性使用浏览器前缀 -webkit -moz
    "property-no-vendor-prefix": null,
    // 允许 Vue 的 global
    "selector-pseudo-class-no-unknown": [
      true,
      {
        ignorePseudoClasses: ["global"],
      },
    ],
    // 允许 Vue 的 v-deep
    "selector-pseudo-element-no-unknown": [
      true,
      {
        ignorePseudoElements: ["v-deep"],
      },
    ],
    // 指定样式的排序 修复后会帮我们自动整理CSS样式的顺序
    "order/properties-order": [
      "position",
      "top",
      "right",
      "bottom",
      "left",
      "z-index",
      "display",
      "justify-content",
      "align-items",
      "float",
      "clear",
      "overflow",
      "overflow-x",
      "overflow-y",
      "padding",
      "padding-top",
      "padding-right",
      "padding-bottom",
      "padding-left",
      "margin",
      "margin-top",
      "margin-right",
      "margin-bottom",
      "margin-left",
      "width",
      "min-width",
      "max-width",
      "height",
      "min-height",
      "max-height",
      "font-size",
      "font-family",
      "text-align",
      "text-justify",
      "text-indent",
      "text-overflow",
      "text-decoration",
      "white-space",
      "color",
      "background",
      "background-position",
      "background-repeat",
      "background-size",
      "background-color",
      "background-clip",
      "border",
      "border-style",
      "border-width",
      "border-color",
      "border-top-style",
      "border-top-width",
      "border-top-color",
      "border-right-style",
      "border-right-width",
      "border-right-color",
      "border-bottom-style",
      "border-bottom-width",
      "border-bottom-color",
      "border-left-style",
      "border-left-width",
      "border-left-color",
      "border-radius",
      "opacity",
      "filter",
      "list-style",
      "outline",
      "visibility",
      "box-shadow",
      "text-shadow",
      "resize",
      "transition",
    ],
  },
};


配置.stylelintignore忽略文件
/dist/*
/public/*
public/*
/mock/*
/node_modules/*
/types/*
配置 package.json指令
{
  "script": {
    "lint:style": "stylelint \"src/**/*.{css,less,vue}\" --fix",
  }
}
同步修改 .vscode/settings.json文件
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit", //保存时eslint自动修复
    "source.fixAll.stylelint": "explicit" //启用stylelint保存时自动修复
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode", // 指定 Prettier 为默认格式化工具
  "editor.formatOnSave": true, // 启用保存时自动格式化
  "eslint.validate": ["javascript", "typescript", "vue"], // 检查的文件类型
  "stylelint.validate": ["css", "less", "postcss", "scss", "sass", "vue"], // 检查的文件类型
  "css.validate": false, // 关闭 VS Code 自带的 CSS 检查
  "less.validate": false,
  "scss.validate": false
}

配置Husky

一般来说可以在提交代码(git commit)之前做一些团队规范处理
主要是用到下面两个钩子 pre-commitcommit-msg

用到hooks作用

  • 在 pre-commit 触发时进行代码格式验证。
  • 在 commit-msg 触发时对 commit 消息和提交用户进行验证。
git hook执行时期备注
pre-commitgit commit 执行前git commit --no verify 命令可以绕过该钩子
commit-msggit commit 执行前git commit --no verify 命令可以绕过该钩子
安装依赖
pnpm install -D husky
配置 package.jsonhusky指令
{
  "scripts": {
    "prepare": "husky install",
  }
}
初始化husky
pnpm run prepare

注意:运行后会在根目录生成.husky文件,我现在是最新的"husky": "^9.1.7",版本,需要使用到的目录文件已经有了,后续就手动修改对应git钩子文件就行了

目录结构
.husky/_/
├── pre-commit      # 提交前钩子(执行 lint-staged)
├── commit-msg      # 提交信息钩子(执行 commitlint)
└── .gitignore
配置LintStaged
  • 只检查暂存区(git add 过的)文件,避免全量扫描,速度极快
*它们如何协作? husky+LintStaged
流程如下
    participant 开发者
    participant Git
    participant Husky
    participant lint-staged

    开发者->>Git: git commit -m "feat: update"
    Git->>Husky: 触发 pre-commit 钩子
    Husky->>lint-staged: 执行 npx lint-staged
    lint-staged->>ESLint: 只检查暂存区的.js文件
    lint-staged->>Prettier: 只格式化暂存区的.css文件
    alt 检查通过
        lint-staged-->>Git: 允许提交
    else 检查失败
        lint-staged-->>开发者: 报错并终止提交
    end

安装依赖
pnpm install -D lint-staged

配置 package.jsonlint-staged指令
{
  "script": {
    "lint:lint-staged": "lint-staged",
  }
}
配置 package.json
"lint-staged": {
  "*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "prettier --write"
  ],
  "{!(package)*.json,*.code-snippets,.!(browserslist)*rc}": [
    "prettier --write--parser json"
  ],
  "package.json": [
    "prettier --write"
  ],
  "*.vue": [
    "eslint --fix",
    "prettier --write",
    "stylelint --fix"
  ],
  "*.{scss,less,styl,html}": [
    "stylelint --fix",
    "prettier --write"
  ],
  "*.md": [
    "prettier --write"
  ]
}

配置 package.json lint-staged总结
文件类型使用的工具作用
.js/.jsx/.ts/.tsxESLint + PrettierJS/TS 代码检查和格式化
.json(非 package.jsonPrettierJSON 配置文件格式化
package.jsonPrettier依赖文件格式化
.vueESLint + Prettier + StylelintVue 单文件组件的 JS/HTML/CSS 检查
.scss/.less/.styl/.htmlStylelint + Prettier样式文件检查和格式化
.mdPrettierMarkdown 文档格式化
当我们使用 git commit -m "xxx" 时,lint-staged 会自动执行帮我们进行代码质量与风格的修复
结合husky编辑 pre-commit 钩子并运行lint-staged脚本

直接编辑 .husky/pre-commit 文件

#!/usr/bin/env sh
. "$(dirname "$0")/husky.sh"    # $(dirname "$0")表示文件所在目录: .husky/_

set -e  # 如果任何命令失败,立即退出

echo "🔍 正在运行代码检查..."
pnpm run lint:lint-staged

echo "✅ 检查通过,可以提交!"

提交一个错的css代码用git命令和vscode 测试一下,看能不能捕获错误 image.png

配置CommitLint
  • commitlint 用于检查 Git 提交信息是否符合规范,确保团队提交风格一致。
安装依赖
pnpm install -D @commitlint/cli  @commitlint/config-conventional

配置 commitlint.config.js文件

在项目根目录创建 commitlint.config.js配置文件内容如下

规则由名称和数组组成:<配置名称>: [警报级别, 是否启用, 规则对应的值]

  • 警报级别

    0 无提示 disable
    1 警告 warning
    2 错误 error
    
  • 是否启用

    always 启用
    never 禁用
    
export default {
  ignores: [(commit) => commit.includes("init")],
  extends: ["@commitlint/config-conventional"],
  rules: {
    // 信息以空格开头
    "body-leading-blank": [2, "always"],
    "footer-leading-blank": [2, "always"],
    // 信息最大长度
    "header-max-length": [2, "always", 108],
    // 信息不能未空
    "subject-empty": [2, "never"],
    // 信息类型不能未空
    "type-empty": [2, "never"],
    // 提交信息的类型
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "perf",
        "style",
        "docs",
        "test",
        "refactor",
        "build",
        "ci",
        "chore",
        "revert",
        "wip",
        "workflow",
        "types",
        "release",
        "temp",
      ],
    ],
  },
};

常用提交类型(type
类型说明
feat新增功能
fix修复 Bug
docs文档变更
style代码格式(空格、分号等)
refactor代码重构(非功能修改)
test测试相关
chore构建/工具变更
revert回滚提交
配置 huksy commit-msg

直接编辑 .husky/commit-msg 文件

#!/usr/bin/env sh
. "$(dirname "$0")/husky.sh"  # 加载 husky 环境

set -e  # 失败时退出

# 使用 commitlint 检查提交信息格式
npx --no-install commitlint --edit "$1"
测试一下

image.png

最后当前package.json文件

{
  "name": "vue3-app",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "lint:lint-staged": "lint-staged",
    "prepare": "husky install",
    "lint:eslint": "eslint --cache --max-warnings 0 {src,mock}/**/*.{js,vue,ts,tsx} --fix",
    "lint:prettier": "prettier --write **/*.{js,json,tsx,css,less,scss,vue,html,md}",
    "lint:style": "stylelint \"src/**/*.{css,less,vue}\" --fix",
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.13"
  },
  "devDependencies": {
    "@commitlint/cli": "^19.8.0",
    "@commitlint/config-conventional": "^19.8.0",
    "@eslint/create-config": "^1.6.0",
    "@eslint/js": "^9.24.0",
    "@vitejs/plugin-vue": "^5.2.1",
    "eslint": "^9.24.0",
    "eslint-config-prettier": "^10.1.1",
    "eslint-plugin-prettier": "^5.2.6",
    "eslint-plugin-vue": "^10.0.0",
    "globals": "^16.0.0",
    "husky": "^9.1.7",
    "lint-staged": "^15.5.0",
    "postcss-html": "^1.8.0",
    "postcss-less": "^6.0.0",
    "prettier": "^3.5.3",
    "stylelint": "^16.18.0",
    "stylelint-config-html": "^1.1.0",
    "stylelint-config-standard": "^38.0.0",
    "stylelint-config-standard-vue": "^1.0.0",
    "stylelint-less": "^3.0.1",
    "stylelint-order": "^6.0.4",
    "vite": "^6.2.0"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "{!(package)*.json,*.code-snippets,.!(browserslist)*rc}": [
      "prettier --write--parser json"
    ],
    "package.json": [
      "prettier --write"
    ],
    "*.vue": [
      "eslint --fix",
      "prettier --write",
      "stylelint --fix"
    ],
    "*.{scss,less,styl,html}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}