vue3 admin 保姆教学指南 | 项目规范集成教程,看完秒懂项目中各种奇怪的文件和配置

语言: CN / TW / HK

一个项目要有统一的规范,需要使用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

依赖说明

增加 .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提供的生命周期钩子)这个命令。

最终我们的项目被集成了这个样子

image.png

上述规范适集成思路用于各种项目,比如UI组件库,工具库,后台管理系统等等,只不过针对不同的技术有不同的lint包来配置,只要看懂了我的教程,你就可以自己配置了。

代码地址

https://gitee.com/guigu-fe/guigu-sph-mall-admin/tree/template%2Fvue3-app-template/

欢迎star,欢迎PR。