前言
如何基于 Vite 的 Vue3 项目中集成完整的代码规范工具链,包括:
- ESLint - JavaScript/TypeScript 代码语法检查
- Prettier - 代码风格格式化
- StyleLint - CSS/SCSS 样式语法检查
- Husky:Git 钩子管理
- LintStaged - Git 暂存区文件检查
- CommitLint - Git 提交信息规范检查
前置知识Vscode需要安装ESLint + Stylelint + Prettier- Code formatter插件结合使用
用 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
配置 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
- 下载ESLint插件
- 输入
Ctrl+Shift+P
打开命令面板 - 输入
setting.json
,选择Workspace Settings
,生成.vscode
文件
.vscode/settings.json
: 配置文件内容如下
{
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit" //保存时自动修复,新版推荐写法(替代 true)
},
"eslint.validate": ["javascript", "typescript", "vue"], // 检查的文件类型
"eslint.enable": true // 启用 ESLint
}
最后定义一个未声明的变量林文强
测试一下代码,保存的时候能自动缩进,还有提示代码语法错误那就可以了
配置 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配置文件
- 配置文件名称可以为:.stylelintrc.js、.stylelint.config.js (根据个人习惯选择即可)
- 更多详细配置规则请查看官方文档:List of rules | Stylelint 中文文档 (bootcss.com)
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-commit 和 commit-msg
用到hooks作用:
- 在 pre-commit 触发时进行代码格式验证。
- 在 commit-msg 触发时对 commit 消息和提交用户进行验证。
git hook | 执行时期 | 备注 |
---|---|---|
pre-commit | git commit 执行前 | git commit --no verify 命令可以绕过该钩子 |
commit-msg | git commit 执行前 | git commit --no verify 命令可以绕过该钩子 |
安装依赖
pnpm install -D husky
配置 package.json
husky指令
{
"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.json
lint-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 /.tsx | ESLint + Prettier | JS/TS 代码检查和格式化 |
.json (非 package.json ) | Prettier | JSON 配置文件格式化 |
package.json | Prettier | 依赖文件格式化 |
.vue | ESLint + Prettier + Stylelint | Vue 单文件组件的 JS/HTML/CSS 检查 |
.scss /.less /.styl /.html | Stylelint + Prettier | 样式文件检查和格式化 |
.md | Prettier | Markdown 文档格式化 |
当我们使用 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 测试一下,看能不能捕获错误
配置CommitLint
commitlint
用于检查 Git 提交信息是否符合规范,确保团队提交风格一致。
安装依赖
pnpm install -D @commitlint/cli @commitlint/config-conventional
配置 commitlint.config.js
文件
在项目根目录创建 commitlint.config.js
:
配置文件内容如下
- 官方文档的配置规则讲解:Rules (commitlint.js.org)
规则由名称和数组组成:<配置名称
>: [警报级别, 是否启用, 规则对应的值
]
-
警报级别
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"
测试一下
最后当前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"
]
}
}