手把手教你搭建规范的团队vue项目，包含commitlint，eslint，prettier，husky，commitizen等等

1，前言

---

本文主要分享一个项目的规范约束从0到1的流程，从通过vue-cli创建项目，到团队协作插件安装（husky、eslint、commitlint、prettier等）。

• 本文vue-cli脚手架为5.x
• 本文webpack版本为5.x
• 本文vue版本为3.x

2，创建项目

---

如果你的vue-cli不是5.x版本，并且不知道怎么创建vue-cli项目，请先查看该文章：传送门

首先进入一个空间足够的磁盘，比如楼主是进的L盘，输入以下命令：

vue create demo

创建完毕后，项目结构如下图：

此时可以打开package.json，查看项目当前装的依赖。默认是已经安装了eslint、babel和vue

"dependencies": {
   "core-js": "^3.8.3",
   "vue": "^3.2.13"
 },
 "devDependencies": {
   "@babel/core": "^7.12.16",
   "@babel/eslint-parser": "^7.12.16",
   "@vue/cli-plugin-babel": "~5.0.0",
   "@vue/cli-plugin-eslint": "~5.0.0",
   "@vue/cli-service": "~5.0.0",
   "eslint": "^7.32.0",
   "eslint-plugin-vue": "^8.0.3"
 }

2，安装vue全家桶

---

先安装一些常用的vue生态，包括axios，vue-router，vuex，qs，element-plus等，具体使用可看下方教程链接：

npm install axios vue-router vuex qs element-plus --save

• 助你上手Vue3全家桶之Vue3教程
• 助你上手Vue3全家桶之VueX4教程
• 助你上手Vue3全家桶之Vue-Router4教程

再安装typescript

npm install typescript@4.7 --save -D

3，配置prettier

---

1. 首先在根目录创建.prettierrc.js文件，这个文件是项目的prettier规则，内容如下：

   module.exports = {
     tabWidth: 2, // tab缩进大小,默认为2
     useTabs: false, // 使用tab缩进，默认false
     semi: false, // 使用分号, 默认true
     singleQuote: true, // 使用单引号, 默认false(在jsx中配置无效, 默认都是双引号)
     jsxBracketSameLine: false, // 在jsx中把'>' 是否单独放一行
     jsxSingleQuote: false, // 在jsx中使用单引号代替双引号
     proseWrap: 'preserve', // "always" - 当超出print width（上面有这个参数）时就折行 "never" - 不折行 "perserve" - 按照文件原样折行
     trailingComma: 'none', // 对象最后一项默认格式化会加逗号
     arrowParens: 'avoid', // 箭头函数参数括号 默认avoid 可选 avoid(能省略括号的时候就省略)| always(总是有括号)
     bracketSpacing: true, // 对象中的空格 默认true{ foo: bar } false:{foo: bar}
     printWidth: 100 // 一行多长，超过的会换行
   }
   

2. 然后在根目录创建.prettierignore文件，这个是设置有那些文件需要忽略eslint的检查，内容如下：

   node_modules
   dist
   public
   .vscode
   

3. 安装prettier的扩展。eslint-plugin-prettier，eslint-config-prettier

   npm install eslint-config-prettier eslint-plugin-prettier --save -D
   

4，配置eslint

---

1. 首先在根目录创建.eslintrc.js，这个文件是项目的eslint规则，内容如下：

   module.exports = {
     root: true,
     env: {
       browser: true,
       node: true,
       commonjs: true,
       es6: true,
       amd: true,
     },
     globals: { // 允许的全局变量
       TAny: true,
       TAnyType: true,
       TAnyArray: true,
       TAnyFunc: true,
       TDictArray: true,
       TDictObject: true
     },
     extends: ['plugin:vue/vue3-essential', 'airbnb-base', '@vue/typescript/recommended'], // 扩展插件
     parserOptions: {
       ecmaVersion: 2020,
       sourceType: 'module',
       parser: '@typescript-eslint/parser',
       ecmaFeatures: {
         tsx: true, // 允许解析TSX
         jsx: true,
       }
     },
     settings: {
       'import/resolver': {
         node: { extensions: ['.js', '.jsx', '.ts', '.tsx', 'vue'] }
       }
     },
     plugins: ['prettier'],
     rules: {
       // 0表示不不处理，1表示警告，2表示错误并退出
       'vue/multi-word-component-names': 'off', // 要求组件名称始终为多字
       '@typescript-eslint/no-unused-vars': [
         'error',
         { varsIgnorePattern: '.*', args: 'none' }
       ],
       camelcase: 1, // 驼峰命名
       'prettier/prettier': 0, // 会优先采用prettierrc.json的配置，不符合规则会提示错误
       'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
       'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
       'comma-dangle': 'off',
       'import/prefer-default-export': 'off', // 优先export default导出
       'no-param-reassign': 'off', // 函数参数属性的赋值
       semi: 'off',
       '@typescript-eslint/no-explicit-any': 'warn',
       'no-unused-expressions': 'off', // 联式调用使用?
       'import/no-cycle': 'off', // 导入循环引用报错
       'arrow-parens': 'off', // 箭头函数一个参数可以不要括号
       'no-underscore-dangle': 'off', // 无下划线
       'no-plusplus': 'off', //  使用一元运算符
       'object-curly-newline': 'off',
       'no-restricted-syntax': 'off', // 使用for of
       'operator-linebreak': 'off', // after
       'arrow-body-style': 'off',
       '@typescript-eslint/explicit-module-boundary-types': 'off', // ts每个函数都要显式声明返回值
       // 暂时屏蔽检测@别名
       'import/no-useless-path-segments': 'off',
       'import/no-unresolved': 'off',
       'import/extensions': 'off',
       'import/no-absolute-path': 'off',
       'import/no-extraneous-dependencies': 'off',
       'newline-per-chained-call': ['error', { ignoreChainWithDepth: 10 }],
       'linebreak-style': [0, 'error', 'windows'],
       'no-shadow': 'off', // 注意你必须禁用基本规则，因为它可以报告不正确的错误
       '@typescript-eslint/no-shadow': ['error'],
       '@typescript-eslint/member-delimiter-style': [
         'error',
         {
           multiline: {
             delimiter: 'none',
             requireLast: true,
           },
           singleline: {
             delimiter: 'semi',
             requireLast: false,
           },
         },
       ],
       'keyword-spacing': [
         2,
         {
           before: true,
           after: true,
         },
       ]
     }
   }
   

2. 然后在根目录创建.eslintignore文件，这个是设置那些文件需要忽略eslint的检查，内容如下：

   node_modules
   dist
   .vscode
   

3. 安装eslint的扩展。eslint-config-airbnb-base，@typescript-eslint/eslint-plugin，@vue/eslint-config-typescript，@typescript-eslint/parser，@vue/eslint-config-typescript，eslint-plugin-import。

   npm install eslint-config-airbnb-base @typescript-eslint/eslint-plugin @vue/eslint-config-typescript @typescript-eslint/parser @vue/eslint-config-typescript eslint-plugin-import --save -D
   

到这一步，就可以在package.json文件里的scripts对象里添加一行自动修复文件的命令 lint-fix：

"scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint-fix": "vue-cli-service lint --fix ./src --ext .vue,.js,.ts"
  }

在项目根目录打开终端，输入npm run lint-fix，会按照你的eslint要求自动进行修复，部分修复不了的需要手动修改。

5，配置husky + git钩子

---

husky是一个让配置git钩子变得更简单的工具，支持所有的git钩子。它可以将git内置的钩子暴露出来，很方便地进行钩子命令注入，而不需要在.git/hooks目录下自己写shell脚本了。您可以使用它来lint您的提交消息、运行测试、lint代码等。当你commit或push的时候。husky触发所有git钩子脚本。

1. 安装husky

   npm install husky --save -D
   

2. 启用husky，启用后，根目录会出现一个.husky的文件夹

   npx husky install
   

3. 编辑package.json文件，在scripts中添加"prepare": "husky install"命令

   "scripts": {
       "serve": "vue-cli-service serve",
       "build": "vue-cli-service build",
       "lint-fix": "vue-cli-service lint --fix ./src --ext .vue,.js,.ts",
       "prepare": "husky install"
     },
   

4. 在.husky文件夹中，新建pre-commit文件，写入以下代码：

   #!/bin/sh
   . "$(dirname "$0")/_/husky.sh"
   
   npx lint-staged --allow-empty
   

5. 安装lint-staged，这是本地暂存代码的检查工具，当你git提交代码时，会自动检查是否符合项目eslint和prettier规范

   npm install lint-staged --save -D
   

6. 在项目根目录创建.lintstagedrc.json文件，写入以下代码：

   {
     "*.{ts,js,vue,tsx,jsx}": ["npm run lint-fix", "prettier --write"]
   }
   

到这一步，git提交的时候，会自动根据项目eslint和prettier规范修复代码并提交，如果碰到修复不了的，会取消提交。

6，配置commitlint

---

在git提交时，如果能找按照规范写好提交信息，能提高可读性以及项目维护效率，方便回溯。这里我们使用commitlint规范git commit提交的信息。

6.1，配置commitlint格式检查

1. 首先安装@commitlint/cli和@commitlint/config-conventional（如果要自定义提交规范，就不用安装@commitlint/config-conventional）

   npm install @commitlint/cli @commitlint/config-conventional --save -D
   

2. 在项目根目录的.husky文件夹中，新建commit-msg文件，写入以下内容：

   #!/bin/sh
   . "$(dirname "$0")/_/husky.sh"
   
   npx commitlint --edit $1
   

3. 在项目根目录新建commitlint.config.js文件，写入以下内容：

   /*
   "off"或者0:关闭规则 "warn"或1:开启规则抛出警告 "error"或2:开启规则抛出错误
   */
   module.exports = {
     extends: ['@commitlint/config-conventional'],
     rules: {
       'body-leading-blank': [2, 'always'], // body上面有换行
       'footer-leading-blank': [1, 'always'], // footer上面有换行
       'header-max-length': [2, 'always', 108], // header上最大108字符
       'type-case': [0],
       'type-empty': [0],
       'scope-empty': [0],
       'scope-case': [0],
       'subject-full-stop': [0, 'never'],
       'subject-case': [0, 'never'],
       'type-enum': [
         2,
         'always',
         [
           'feat', // 新增功能、页面
           'fix', // 修补bug
           'docs', // 修改文档、注释
           'style', // 格式：不影响代码运行的变动、空格、格式化等等
           'ui', // ui修改：布局、css样式等等
           'hotfix', // 修复线上紧急bug
           'build', // 改变构建流程，新增依赖库、工具等（例如:修改webpack）
           'refactor', // 代码重构，未新增任何功能和修复任何bug
           'revert', // 回滚到上一个版本
           'perf', // 优化：提升性能、用户体验等
           'ci', // 对CI/CD配置文件和脚本的更改
           'chore', // 其他不修改src或测试文件的更改
           'test', // 测试用例：包括单元测试、集成测试
       	'update' // 更新：普通更新
         ]
       ]
     }
   }
   

4. 在git提交时，填写的commit信息格式规范如下：

   <type>(<scope>): <subject> // 必填
   // 空一行
   <body> // 必填
   // 空一行
   <footer> // 可忽略不填
   

   例子：

   git commit -m 'style(home.vue):修改样式
   
   修改了home.vue的样式，添加了背景色'
   

6.2，安装自定义的辅助提交依赖commitizen

1. 首先需要安装commitizen和commitlint-config-cz和cz-customizable

   npm install commitizen commitlint-config-cz cz-customizable --save -D
   

2. 然后新建.cz-config.js文件，内容如下：

   'use strict'
   module.exports = {
     types: [
       { value: 'feat', name: '新增：新增功能、页面' },
       { value: 'fix', name: 'bug：修复某个bug' },
       { value: 'docs', name: '文档：修改增加文档、注释' },
       { value: 'style', name: '格式：不影响代码运行的变动、空格、格式化等等' },
       { value: 'ui', name: 'ui修改：布局、css样式等等' },
       { value: 'hotfix', name: 'bug：修复线上紧急bug' },
       { value: 'build', name: '测试：添加一个测试' },
       { value: 'refactor', name: '重构：代码重构，未新增任何功能和修复任何bug' },
       { value: 'revert', name: '回滚：代码回退到某个版本节点' },
       { value: 'perf', name: '优化：提升性能、用户体验等' },
       { value: 'ci', name: '自动化构建：对CI/CD配置文件和脚本的更改' },
       { value: 'chore', name: '其他修改：不修改src目录或测试文件的修改' },
       { value: 'test', name: '测试：包括单元测试、集成测试' },
       { value: 'update', name: '更新：普通更新' }
     ],
     // 交互提示信息
     messages: {
       type: '选择一种你的提交类型：',
       scope: '选择一个影响范围（可选）:',
       customScope: '表示此更改的范围：',
       subject: '短说明：\n',
       body: '长说明，使用"|"符号换行（可选）：\n',
       breaking: '非兼容性说明（可选）：\n',
       footer: '关闭的issue，例如：#31, #34（可选）：\n',
       confirmCommit: '确定提交说明?（yes/no）'
     },
     allowCustomScopes: true,
     // 设置选择了那些type，才询问 breaking message
     allowBreakingChanges: ['feat', 'fix', 'ui', 'hotfix', 'update', 'perf'],
     subjectLimit: 100
   }
   

3. 然后修改commitlint.config.js文件的extends选项，改成['cz']

   module.exports = {
   	extends: ['cz'],
   	......
   }
   

4. 编辑package.json文件，在scripts中添加"commit": "git-cz"命令

   "scripts": {
       "serve": "vue-cli-service serve",
       "build": "vue-cli-service build",
       "lint-fix": "vue-cli-service lint --fix ./src --ext .vue,.js,.ts",
       "prepare": "husky install",
       "commit": "git-cz"
   }
   

5. 在根目录终端，运行以下命令初始化命令行的选项信息：

   npx commitizen init cz-customizable --save-dev --save-exact
   

6. 运行完成后，在package.json中会出现如下选项：

   "config": {
       "commitizen": {
         "path": "./node_modules/cz-customizable"
       }
    }
   

此时，代码提交过程就多了一个可选的规范提示，提交流程是先git add .，提交到暂存区，然后终端运行npm run commit，根据提示选择信息或者输入即可，最后git push推送，如下gif图所示：

附几个我个人的项目模板：

• Vite-H5-Template
• Vite-PC-Template
• Webpack-PC-Template
• H5-V2-Template
• Uniapp-Cli-V2-Template
• Uniapp-Cli-Ts-V3-Template
• PC-V2-Template

---

如果看了觉得有帮助的，我是@上进的鹏多多，欢迎 点赞 关注 评论；

往期文章

• Vue2全家桶+Element搭建的PC端在线音乐网站
• vue3+element-plus配置cdn
• 助你上手Vue3全家桶之Vue3教程
• 助你上手Vue3全家桶之VueX4教程
• 助你上手Vue3全家桶之Vue-Router4教程
• 超详细！Vue的九种通信方式
• 超详细！Vuex手把手教程
• 使用nvm管理node.js版本以及更换npm淘宝镜像源
• vue中利用.env文件存储全局环境变量，以及配置vue启动和打包命令
• 超详细！Vue-Router手把手教程

个人主页

• CSDN
• GitHub
• 简书
• 博客园
• 掘金