用Eslint+Prettier+husky+commitlint+lint-staged+commitizen快速搭建标准化编程规范项目

• 专栏地址：前端编译和工程化
• 本文作者：前端小东

一、前言

编程格式规范已经是目前各大互联网公司都在遵循的一种规范，其中一些大厂有自己出版的规范，如：

• 京东凹凸实验室前端代码规范
• 腾讯前端代码规范
• 百度前端代码规范文档

整体规范大体可以分为两类：

（1）代码格式规范

对于代码格式规范，我们通过Eslint+Prettier+Vscode配合进行处理，可以实现在保存代码时，自动规范化代码格式的目的。

（2）代码提交规范

对于代码提交规范，我们通过使用husky来监测git hooks钩子，通过以下插件完成对应的配置：

1. commitlint：用于检测提交的信息
2. lint-staged：检查本次修改更新的代码，并自动修复并且可以添加到暂存区
3. pre-commit：git hooks的钩子，在代码提交前检查代码是否符合规范，不符合规范将不可被提交
4. commit-msg：git hooks的钩子，在代码提交前检查commit信息是否符合规范
5. commitizen：git的规范化提交工具，帮助你填写commit信息，符合约定式提交要求

二、代码格式规范

（1）初始化一个项目

（2）安装ESlint

npm install eslint --save-dev

安装完后，打开终端，执行命令npx elint --init根据自己的需求生成配置：

然后会在根目录多了一个.eslintrc.js文件：

module.exports = {
    "env": {
        "browser": true,
        "es2021": true,
        "node": true
    },
    "extends": "eslint:recommended",
    "parserOptions": {
        "ecmaVersion": 12,
        "sourceType": "module"
    },
    "rules": {}
};
  

测试一下，新增一个index.js文件，输入内容：

控制台执行命令：

npx eslint index.js

出现这个报错，说明eslint生效了，我们在.eslintrc.js文件中添加规则no-console：

module.exports = {
    "env": {
        "browser": true,
        "es2021": true,
        "node": true
    },
    "extends": "eslint:recommended",
    "parserOptions": {
        "ecmaVersion": 12,
        "sourceType": "module"
    },
    "rules": {
    	"no-console": "off"
    }
};

rules 可以配置很多规则，具体可以看Eslint Rules

然后index.js修改为：

再次执行:

npx eslint index.js

控制台不再报错，并且可以正常输出变量。

（3）Vscode 安装 Eslint 插件

上面每次都需要执行npx eslint xxx才能校验，单个文件还好，多个文件就没法玩了。有没有办法在代码保存的时候自动执行Eslint，只需要安装Eslint插件即可：

在setting.json文件中添加以下内容（安装完Eslint插件应该会自动添加，如果没有请手动补上）：

"editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
}

编辑器就会出现报错提示了：

在package.json脚本中添加eslint命令，表示Eslint检测当前目录下所有文件：

"scripts": {
    "eslint": "eslint ./**/*"
}

在根目录下新增.eslintignore文件，表示Eslint检测时排除掉以下文件：

node_modules
package.json
package-lock.json

新增多一个test.js文件：

然后在控制台输入命令：

npm run eslint

多个文件都可以检测得到了。

（4）使用 Prettier 自动修复

Eslint可以帮助我们检测代码，我们需要使用Prettier自动修复代码，让我们的代码符合Eslint标准，在Vscode中安装Prettier插件：

在项目根目录中新建 .prettierrc.js 文件，该文件为 perttier 默认配置文件:

modules.exports = {
  // 结尾不使用分号
  "semi": true,
  // 使用单引号
  "singleQuote": true,
  // 多行逗号分割的语法中，最后一行不加逗号
  "trailingComma": "none"
}

更多配置，可以查看Prettier Options

在设置中，搜索 save ，勾选 Format On Save：

然后在setting.json中增加配置：

"[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

设置完需要重启，否则不会生效

然后在index.js文件中输入一些不规范的代码：

上面的代码，保存后自动修复成了规范的代码，解决了以下问题：

1. 使用了双引号
2. 结尾使用了分号
3. 缩进不一致
4. 多行代码结尾使用了逗号

以上就是代码格式规范的全部内容。

三、代码提交规范

完成上述的代码格式规范后，接下来当然是要把我们的代码提交上库了，团队中为了规范化提交，通常使用git hooks来防止一些不规范的代码被提交到仓库中，简单的列举一些常见的hooks钩子：

Git Hook	调用时机	说明
pre-applypatch	git am执行前
applypatch-msg	git am执行前
post-applypatch	git am执行后	不影响git am的结果
pre-commit	git commit执行前	可以用git commit --no-verify绕过
commit-msg	git commit执行前	可以用git commit --no-verify绕过
post-commit	git commit执行后	不影响git commit的结果
pre-merge-commit	git merge执行前	可以用git merge --no-verify绕过。
prepare-commit-msg	git commit执行后，编辑器打开之前
pre-rebase	git rebase执行前
post-checkout	git checkout或git switch执行后	如果不使用--no-checkout参数，则在git clone之后也会执行。
post-merge	git commit执行后	在执行git pull时也会被调用
pre-push	git push执行前
pre-receive	git-receive-pack执行前
update
post-receive	git-receive-pack执行后	不影响git-receive-pack的结果
post-update	当 git-receive-pack对 git push 作出反应并更新仓库中的引用时
push-to-checkout	当 git-receive-pack对git push做出反应并更新仓库中的引用时，以及当推送试图更新当前被签出的分支且receive.denyCurrentBranch配置被设置为updateInstead`时
pre-auto-gc	git gc --auto执行前
post-rewrite	执行git commit --amend或git rebase时
sendemail-validate	git send-email执行前
fsmonitor-watchman	配置core.fsmonitor被设置为.git/hooks/fsmonitor-watchman或.git/hooks/fsmonitor-watchmanv2时
p4-pre-submit	git-p4 submit执行前	可以用git-p4 submit --no-verify绕过
p4-prepare-changelist	git-p4 submit执行后，编辑器启动前	可以用git-p4 submit --no-verify绕过
p4-changelist	git-p4 submit执行并编辑完changelist message后	可以用git-p4 submit --no-verify绕过
p4-post-changelist	git-p4 submit执行后
post-index-change	索引被写入到read-cache.c do_write_locked_index后

详细的 hooks 的介绍，可点击这里查看

最常用的其实就是上面表格中标粗的pre-commit和commit-msg：

1. commit-msg：可以用来规范化标准格式，并且可以按需指定是否要拒绝本次提交
2. pre-commit：会在提交前被调用，并且可以按需指定是否要拒绝本次提交

（1）使用 husky+commitlint 检查提交描述是否符合规范要求

我们使用以下工具帮我们规范化提交：

1. commitlint：用于检查提交信息
2. husky：是git hooks工具

首先要保证npm在7.x版本以上，如果不是，安装最新的npm版本：

npm install npm -g

安装commitlint：

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

在根目录创建 commitlint.config.js 文件：

module.exports = {
  // 继承的规则
  extends: ['@commitlint/config-conventional'],
  // 定义规则类型
  rules: {
    // type 类型定义，表示 git 提交的 type 必须在以下类型范围内
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新功能 feature
        'fix', // 修复 bug
        'docs', // 文档注释
        'style', // 代码格式(不影响代码运行的变动)
        'refactor', // 重构(既不增加新功能，也不是修复bug)
        'perf', // 性能优化
        'test', // 增加测试
        'chore', // 构建过程或辅助工具的变动
        'revert', // 回退
        'build' // 打包
      ]
    ],
    // subject 大小写不做校验
    'subject-case': [0]
  }
}

安装husky：

npm install husky --save-dev

在控制台输入命令，生成.husky文件夹：

npx husky install

（2）使用 commit-msg 钩子规范化提交信息

添加 commitlint 的 hook 到 husky中，并指令在 commit-msg 的 hooks 下执行 npx --no-install commitlint --edit "$1" 指令：

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

然后测试一下提交：

发现git hooks的钩子commit-msg阻止了我们的提交，输入规范的信息后，再次尝试提交：

代码成功提交，输出log也没有任何问题。

（3）使用 pre-commit 检测提交时代码规范

在代码格式规范章节中，讲解了如何处理代码格式问题，但是这样的一个格式处理问题，他只能够在本地进行处理，并且我们还需要 手动在 Vscode 中配置自动保存才可以。那么这样就会存在一个问题，如果有些人没有配置这个东西怎么办呢？他把一些乱七八糟的代码提交上来怎么办呢？

所以需要使用pre-commit来规避这种风险，我们期望通过 husky 监测 pre-commit 钩子，在该钩子下执行 npm run eslint 指令来去进行相关检测：

npx husky add .husky/pre-commit "npm run eslint"

我们修改一下test.js的内容，然后再次提交：

pre-commit阻止了我们的提交，因为存在不规范的代码

修改不规范代码后，再次提交：

修改后，代码成功提交。

（4）使用 lint-staged 自动修复格式错误

上面我们完成了代码的规范化提交，我们在pre-commit检测到我们代码中有不规范的地方，阻止了我们的提交，我们手动修复了不规范代码后，才能成功提交。那么这存在几个问题：

1. 我们只修改了个别的文件，没有必要检测所有的文件代码格式
2. 它只能给我们提示出对应的错误，我们还需要手动的进行代码修改
3. 修改后需要手动git add .

使用lint-staged可以解决这些问题，安装lint-staged：

npm install lint-staged --save-dev

在package.json中添加配置：

"lint-staged": {
    "./**/*.{js}": [
        "eslint --fix",
        "git add"
    ]
}

然后修改 .husky/pre-commit 文件：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

关闭prettier保存自动修复（否则无法测试）：

修改test.js文件，增加一些不规范的代码：

然后执行提交：

这个过程lint-staged做了两个事情：

1. 如果符合规则：则会提交成功。
2. 如果不符合规则：它会自动执行 eslint --fix 尝试帮你自动修复，如果修复成功则会帮你把修复好的代码提交，如果失败，则会提示你错误，让你修好这个错误之后才能允许你提交代码。

如图所示，代码被修复了，并将test.js提交到了暂存区。

（5）用 commitizen 规范化提交代码

我们每次都需要手动输入commit信息很麻烦，并且容易造成不规范，我们可以使用commitizen来规范化提交代码

全局安装commitizen，注意，这里是全局安装，否则无法执行插件的命令：

npm install commitizen -g

在项目内安装cz-customizable：

npm install cz-customizable --save-dev

添加以下配置到 package.json 中：

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

在根目录创建 .cz-config.js 自定义提示文件：

module.exports = {
  // 可选类型
  types: [
    { value: 'feat', name: 'feat:     新功能' },
    { value: 'fix', name: 'fix:      修复' },
    { value: 'docs', name: 'docs:     文档变更' },
    { value: 'style', name: 'style:    代码格式(不影响代码运行的变动)' },
    { value: 'refactor', name: 'refactor: 重构(既不是增加feature，也不是修复bug)'},
    { value: 'perf', name: 'perf:     性能优化' },
    { value: 'test', name: 'test:     增加测试' },
    { value: 'chore', name: 'chore:    构建过程或辅助工具的变动' },
    { value: 'revert', name: 'revert:   回退' },
    { value: 'build', name: 'build:    打包' }
  ],
  // 消息步骤
  messages: {
    type: '请选择提交类型:',
    customScope: '请输入修改范围(可选):',
    subject: '请简要描述提交(必填):',
    body: '请输入详细描述(可选):',
    footer: '请输入要关闭的issue(可选):',
    confirmCommit: '确认使用以上信息提交？(y/n/e/h)'
  },
  // 跳过问题
  skipQuestions: ['body', 'footer'],
  // subject文字长度默认是72
  subjectLimit: 72
}

然后使用git cz代码git commit命令提交代码：

选择对应的类型，依次执行下去，如需跳过，直接回车即可：

输出log，一切正常：

以上就是代码提交规范的全部内容。

四、总结

标准化规范对于我们的开发流程，代码管理来说具有重要意义，遵循代码格式规范和代码提交规范，有利于我们更好的维护代码，减少错误，减低代码冲突等；每个公司都有自己的标准化规范，本文从快速搭建的角度，带你从0到1搭建一套符合Eslint标准、符合约定式提交要求的项目。其中，像Eslint和Prettier等工具可根据自己项目的需求自定义配置。

五、参考

• 约定式提交
• Eslint
• Prettier
• commitlint
• husky
• commitizen
• git hooks