vue3 admin 保姆教学指南 ｜ 项目规范集成教程，看完秒懂项目中各种奇怪的文件和配置
一个项目要有统一的规范，需要使用eslint+stylelint+prettier来对我们代码质量做检测和修复，需要使用husky来做commit拦截，需要使用commitlint来统一提交规范，需要使用preinstall来统一包管理工具。本文教大家怎么一步一步来集成自己的项目规范。
环境准备
- node v16.17.0
- pnpm 7.11.0
项目初始化
本项目使用vite进行构建，vite官方中文文档参考：cn.vitejs.dev/guide/
项目初始化命令
pnpm create vite
我们这里选择使用vue+typescript的方式进行初始化。
Project name命名为guigu-sph-mall-admin,意为尚品汇商城管理系统。
初始化完成以后进入guiug-sph-mall目录，安装依赖pnpm install,然后运行项目pnpm run dev，在浏览器打开http://localhost:5173/，即可看到预览效果：
配置eslint和prettier
1.eslint验证代码是否符合定义的规范
需要安装以下插件
eslint-plugin-vue：vue.js的Eslint插件（查找vue语法错误，发现错误指令，查找违规风格指南）eslint-plugin-prettier：运行更漂亮的Eslint，使prettier规则优先级更高，Eslint优先级低eslint-config-prettier：让所有与prettier规则存在冲突的Eslint rules失效，并使用prettier进行代码检查@babel/eslint-parser：该解析器允许使用Eslint校验所有babel code
首先安装eslint
pnpm i -D eslint
生成配置文件
// 生成配置文件，.eslintrc.js
npx eslint --init
配置项如下图所示
再安装下面的依赖
pnpm install -D eslint-plugin-import eslint-plugin-vue eslint-plugin-node eslint-plugin-prettier eslint-config-prettier @babel/eslint-parser
修改配置文件如下
module.exports = {
env: {
browser: true,
es2021: true,
node: true,
jest: true,
},
extends: [
'eslint:recommended',
'plugin:vue/vue3-essential',
'plugin:@typescript-eslint/recommended',
'plugin:prettier/recommended',
],
overrides: [],
parser: 'vue-eslint-parser',
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module',
parser: '@typescript-eslint/parser',
},
plugins: ['vue', '@typescript-eslint'],
rules: {
'space-before-function-paren': ['error', 'never'],
semi: 0, // 结尾不要分号
},
}
配置.eslintignore, 防止校验打包的产物
// .eslintignore 配置, 防止校验打包的产物
dist
node_modules
在package.json 中添加运行脚本
"scripts": {
"lint": "eslint src",
"fix": "eslint src --fix",
}
2.pretter格式化代码符合定义的规范
安装包
pnpm install -D eslint-plugin-prettier prettier eslint-config-prettier
在.prettierrc.json添加如下规则：
// .prettierrc.json
{
"singleQuote": true,
"semi": false,
"bracketSpacing": true,
"htmlWhitespaceSensitivity": "ignore",
"endOfLine": "auto",
"trailingComma": "all",
"tabWidth": 2
}
测试一下代码检查是否生效了，我们在main.ts中修改成如下内容
可以看到代码已经红了，然后运行npm run lint来检查一下代码不规范原因
可以看到这里有两处错误，运行npm run fix修改这个错误
这样就符合我们定义的代码规范了。
到此，我们的eslint和prettier配置完毕。
如果出现下面报错，卸载vetur插件，安装TypeScript Vue Plugin (Volar)、Vue Language Features (Volar)插件即可。
配置stylelint
stylelint为css的lint工具。可格式化css代码，检查css语法错误与不合理的写法，指定css书写顺序等。
安装依赖
我们的项目中使用less作为预处理器，安装以下依赖：
pnpm add stylelint postcss postcss-less postcss-html stylelint-config-prettier stylelint-config-recommended-less stylelint-config-standard stylelint-config-standard-vue stylelint-less stylelint-order -D
依赖说明
- stylelint: css样式lint工具
- postcss: 转换css代码工具
- postcss-less: 识别less语法
- postcss-html: 识别html/vue 中的标签中的样式
- stylelint-config-standard: Stylelint的标准可共享配置规则，详细可查看官方文档
- stylelint-config-prettier: 关闭所有不必要或可能与Prettier冲突的规则
- stylelint-config-recommended-less: less的推荐可共享配置规则，详细可查看官方文档
- stylelint-config-standard-vue: lint.vue文件的样式配置
- stylelint-less: stylelint-config-recommended-less的依赖，less的stylelint规则集合
- stylelint-order: 指定样式书写的顺序，在.stylelintrc.js中order/properties-order指定顺序
增加 .stylelintrc 配置文件
{
"extends": [
"stylelint-config-standard",
"stylelint-config-prettier",
"stylelint-config-recommended-less",
"stylelint-config-standard-vue"
],
"plugins": ["stylelint-order"],
"overrides": [
{
"files": ["**/*.(less|css|vue|html)"],
"customSyntax": "postcss-less"
},
{
"files": ["**/*.(html|vue)"],
"customSyntax": "postcss-html"
}
],
"ignoreFiles": [
"**/*.js",
"**/*.jsx",
"**/*.tsx",
"**/*.ts",
"**/*.json",
"**/*.md",
"**/*.yaml"
],
"rules": {
"no-descending-specificity": null,
"selector-pseudo-element-no-unknown": [
true,
{
"ignorePseudoElements": ["v-deep"]
}
],
"selector-pseudo-class-no-unknown": [
true,
{
"ignorePseudoClasses": ["deep"]
}
],
"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"
]
}
}
配置命令
"scripts": {
"lint:style": "stylelint src/**/*.{css,less,vue} --cache --fix"
}
最后配置统一的prettier来格式化我们的js和css，html代码
"scripts": {
"dev": "vite",
"build": "vue-tsc && vite build",
"preview": "vite preview",
"lint": "eslint src",
"fix": "eslint src --fix",
"format": "prettier --write "./**/*.{html,vue,ts,js,json,md}"",
"lint:eslint": "eslint src/**/*.{ts,vue} --cache --fix",
"lint:style": "stylelint src/**/*.{css,less,vue} --cache --fix"
},
当我们运行pnpm format的时候，会把代码直接格式化
vscode保存文件自动修复代码
实现每次保存代码时，自动执行lint命令来修复代码的错误。这个操作需要依赖eslint插件来完成，需要提前在vscode插件市场安装好eslint。然后有两种方式可以配置：
第一种：
直接在项目的跟路径创建.vscode/settings.json文件，然后在其中加入以下配置。
{
// 开启自动修复
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true
}
}
第二种：
用shift+cmd+p,打开搜索命令框，输入settings，选择下面这个
这个文件是vscode的系统配置文件，直接把
// 开启自动修复
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true
}
这段代码复制进去，任何项目打开，都会自动保存文件了。
这里为了让别的人也能方便的使用，我们的项目中直接采用第一种方式。
下面是完整的配置：
{
// 开启自动修复
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true,
"source.fixAll.stylelint": true
},
// 保存的时候自动格式化
"editor.formatOnSave": true,
// 默认格式化工具选择prettier
"editor.defaultFormatter": "esbenp.prettier-vscode",
// 配置该项，新建文件时默认就是space：2
"editor.tabSize": 2,
// stylelint校验的文件格式
"stylelint.validate": ["css", "less", "vue", "html"]
}
配置husky
在上面我们已经集成好了我们代码校验工具，但是需要每次手动的去执行命令才会格式化我们的代码。如果有人没有格式化就提交了，那这个规范就没什么用。所以我们强制让开发人员按照代码规范来提交。
要做到这件事情，可以利用husky来在代码提交之前出发git hook，然后执行pnpm format来自动的格式化我们的代码。
安装husky
pnpm install -D husky
执行
npx husky-init
会在根目录下生成个一个.husky目录，在这个目录下面会有一个pre-commit文件，这个文件里面的命令在我们执行commit的时候就会执行
安装lint-staged
pnpm install -D lint-staged
配置命令
{
"scripts": {
"lint-staged": "lint-staged"
},
"lint-staged": {
"**/*.{js,jsx,ts,tsx,vue}": [
"prettier --write",
"eslint --fix",
"stylelint --fix",
"git add"
]
},
}
在pre-commit文件添加命令
```
!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
pnpm lint-staged ```
当我们对代码进行commit操作的时候，就会执行命令，对代码进行格式化，然后再提交。
配置commitlint校验提交信息
对于我们的commit信息，也是有你统一规范的，不能随便写，比如下面的：
要让每个人都按照统一的标准来执行，我们可以利用commitlint来实现。
安装包
pnpm add @commitlint/config-conventional @commitlint/cli -D
添加配置文件，新建commitlint.config.cjs(注意是cjs)，然后添加下面的代码：
module.exports = {
extends: ['@commitlint/config-conventional'],
// 校验规则
rules: {
'type-enum': [
2,
'always',
[
'feat',
'fix',
'docs',
'style',
'refactor',
'perf',
'test',
'chore',
'revert',
'build',
],
],
'type-case': [0],
'type-empty': [0],
'scope-empty': [0],
'scope-case': [0],
'subject-full-stop': [0, 'never'],
'subject-case': [0, 'never'],
'header-max-length': [0, 'always', 72],
},
}
配置scripts
```
在scrips中添加下面的代码
{ "scripts": { "commitlint": "commitlint --config commitlint.config.cjs -e -V" }, } ```
配置结束，现在当我们填写commit信息的时候，前面就需要带着下面的subject
'feat',
'fix',
'docs',
'style',
'refactor',
'perf',
'test',
'chore',
'revert',
'build',
配置husky
npx husky add .husky/commit-msg
在生成的commit-msg文件中添加下面的命令
```
!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
pnpm commitlint ```
当我们 commit 提交信息时，就不能再随意写了，必须是 git commit -m 'fix: xxx' 符合类型的才可以，需要注意的是类型的后面需要用英文的 :，并且冒号后面是需要空一格的，这个是不能省略的。不然就会像下面这样报错了：
提交成功
强制使用pnpm下载包
根目录创建scritps/preinstall.js文件，添加下面的内容
if (!/pnpm/.test(process.env.npm_execpath || '')) {
console.warn(
`\u001b[33mThis repository must using pnpm as the package manager ` +
` for scripts to work properly.\u001b[39m\n`,
)
process.exit(1)
}
配置命令
"scripts": {
"preinstall": "node ./scripts/preinstall.js"
}
当我们使用npm或者yarn来安装包的时候，就会报错了。原理就是在install的时候会触发preinstall（npm提供的生命周期钩子）这个命令。
最终我们的项目被集成了这个样子
上述规范适集成思路用于各种项目，比如UI组件库，工具库，后台管理系统等等，只不过针对不同的技术有不同的lint包来配置，只要看懂了我的教程，你就可以自己配置了。
代码地址
http://gitee.com/guigu-fe/guigu-sph-mall-admin/tree/template%2Fvue3-app-template/
欢迎star,欢迎PR。