前言

最近心血来潮打算用vue3+ts写一个背诗的h5（为满足自己的背诗习惯）。工欲善其事，必先利其器。先搭个架子啦！虽然是自己一个人写的项目，但是该有的开发规范也是要有的哦！在弄commit规范和自动生成changlog的时候，因为我想要提交表情开头的commit格式而踩尽无数坑！！！故写此文纪念~ 哦！不~ 是归纳总结分享给身边所有想踩坑的人们儿~ 好啦！废话不多说，正式开始我的表演~😝

Commit 规范说明

首先，规范的commit信息能让人一眼清晰明了的知道该提交属于什么类型、修改范围、具体改动，提高团队协作。也方便我们日后找bug，提高团队协作。

下面让我们先来了解下目前大家使用较多的Angular团队规范。

Angluar commit message 规范

该规范将commit信息分为header、body、footer三个部分。

这三部分中哪一行都不能超过100个字符！(angular规范文档中写的)

这里说明下为什么要限制字符长度，因为git会将commit的主题部分超过72个字符的截断显示。效果如下图所示例：

Angluar commit message格式如下：

<type>(<scope>): <subject> // 这一行是Header
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
复制代码

Body部分比较简单，为选填项，指本次提交的具体描述。

Header部分

该规范将 header 分为 type、scope、subject 三部分。

type

type指本次提交的类型，为必填项，必须为以下之一：

feat: 一项新功能
fix: 一个错误修复
docs: 仅文档更改
style: 不影响代码含义的更改（空白，格式，缺少分号等）
refactor: 既不修正错误也不增加功能的代码更改（重构）
perf: 改进性能的代码更改
test: 添加缺失或更正现有测试
build: 影响构建系统或外部依赖项的更改（gulp，npm等）
ci: 对CI配置文件和脚本的更改
chore: 更改构建过程或辅助工具和库，例如文档生成

scope

scope指本次提交的影响范围，为可选项，可以是指定提交更改位置的任何内容。我一般都写更改部分的模块名或者文件名。

当更改影响的范围不止一个范围时，可以使用星号(*)。当然也可以不填写。

subject

subject指本次提交的简要描述，它有如下两个规则。

不要大写第一个字母
末尾没有点（.）

Footer部分选填可以包含以下两种情况

是否产生了破坏性修改

如果当前代码与上一个版本不兼容，如版本升级、接口参数减少、接口删除、迁移等就是破坏性修改。

如果是破坏性修改则 Footer 部分会以BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。如下：

BREAKING CHANGE: 变动的描述\理由\迁移方法
复制代码

关闭 Issue 如果当前 commit 针对某个 issue，那么可以在 Footer 部分关闭这个 issue，也可以关闭多个 issue。填写格式如下：

Close #ISSUE_ID
Closes #ISSUE_ID, #ISSUE_ID
复制代码

如果你使用jira，也可以填写本次修改所影响的JIRA_ID，但是要开启该功能需要先集成 jira与gitlab集成 & jira与github集成。填写格式如下：

re #JIRA_ID // re是关于的意思
fix #JIRA_ID
复制代码

按照以上的格式提交到git上显示如下：

以上是Angular团队的commit规范，大家也可以根据自己团队的习惯去自定义commit规范。

自定义 commit message 规范

这部分我就给大家介绍下，我在这次项目里想要自定义的提交格式，大家可以举一反三。

我想自定义的规范是基于Angluar规范的，只是在它的基础上加个表情gitmoji字段在最打头的位置。格式如下：

:gitmoji: <type>(<scope>): <subject> // 这一行是Header
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
复制代码

其中gitmoji项是必填的，值只能为gitmoji提供的表情列表中的表情。

按照我想要的格式提交到git上显示如下：

这里先说一下，Angluar规范里也有写表情的，要借助 git-cz，它是在subject打头显示的表情，跟我想要的效果不符合😀，是长这个样子滴！

到这里，commit规范格式也讲的差不多啦！这么多乱七八糟的规矩，当然不能让大家手写的啦！🎉🎉🎉🎉当当当当~ 让我们用工具来玩吧！

Commit 规范工具

这里，我们先聊怎么用工具实现 Angluar 默认规范的那种，后面再讲自定义的。不管是 Angluar 版还是自定义版我们都会需要到下面这个工具：

commitizen：它会提供 git cz 命令替代我们的 git commit命令，帮助我们更加方便生成符合规范的 commit message。

Angluar 规范版

全局安装

npm install -g commitizen
复制代码

初始化 commitizen 预设，这里使用官网首选的预设 cz-conventional-changelog

cz-conventional-changelog: 它是 commitizen 的首选适配器，默认有配置，但也可以自定义types，设置header长度之类的属性等。但是它的提示信息都是英文的，不能自定义配置（源码内发现的）。如果需要自定义配置提示信息需要使用 cz-customizable 适配器，文章后面自定义版有这部分内容，点击这里传送。

commitizen init cz-conventional-changelog --save-dev --save-exact
复制代码

全局模式下, 需要 ~/.czrc 配置文件, 为 commitizen 指定 Adapter

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
复制代码

现在大家现在就可以使用 git cz 或 cz 命令来提交commit信息了。

全局安装的可以在任何git init下的目录执行 git cz 或 cz 命令代替 git commit 。

项目内安装

npm install commitizen cz-conventional-changelog -D
复制代码

在package.json中配置，这里是将 cz-conventional-changelog 设置为 commitizen 的 Adapter 。大家也可以选择其他的 Adapter ，文章内自定义版有设置其他 Adapter 的点击此处查看。

"scripts": {
  "commit": "cz"
}
"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}
复制代码

项目内安装，只能在当前项目目录下 npm run commit 代替 git commit。

我为了方便用cz命令，都是全局和项目内都安装，下面演示一下效果：

到这里，就已经实现commit提交自动化了。不过cz-conventional-changelog并没有支持表情，下面我们讲一下怎么加入表情。

表情在subject部分开头的显示

表情在subject部分开头，也可以没有表情，提交效果如下：

实现这种效果，需要用到 streamich/git-cz

1、全局安装

可以不用下载 commitizen ，就可以运行git-cz命令提交commit，如果已经安装了 commitizen 会覆盖 commitizen 的 git cz命令的效果。

npm install -g git-cz

git-cz
复制代码

2、搭配 commitizen 项目内使用

npm install -D git-cz
复制代码

package.json 中 commitizen 的适配器为 git-cz:

{
  "config": {
    "commitizen": {
      "path": "git-cz"
    }
  }
}
复制代码

运行以下命令

npx git-cz
复制代码

效果如下，提交的commit在subject开头有表情：

😭我的电脑表情显示乱码，还没有解决（有知道怎么解决的朋友麻烦评价区告诉我，我实在是搞不出来了😰），不过只是电脑上乱码显示，到github上看是正常显示的，所以也并不会很妨碍我提交，只是看着心里不得劲。

这里还有个小问题，在我实际操作中，发现只要 install 了 git-cz 就可以运行 npx git-cz 命令，显示的选择文本等也是符合git-cz默认设置的，不需要 package.json 设置配置器，不知道为什么跟官网描述不一致，还没弄清楚😥。

git-cz 工具它也是提供自定义配置的，但是配置项有限。在根目录添加 changelog.config.js ，下面为大家示例一个官方配置，大家可以在streamich/git-cz官方看更多配置。

./changelog.config.js

module.exports = {
  "disableEmoji": false,
  "list": [
    "test",
    "feat",
    "fix",
    "chore",
    "docs",
    "refactor",
    "style",
    "ci",
    "perf"
  ],
  "maxMessageLength": 64,
  "minMessageLength": 3,
  "questions": [
    "type",
    "scope",
    "subject",
    "body",
    "breaking",
    "issues",
    "lerna"
  ],
  "scopes": [],
  "types": {
    "chore": {
      "description": "Build process or auxiliary tool changes",
      "emoji": "🤖", // 当前类型的commit所显示的表情
      "value": "chore"
    },
    "ci": {
      "description": "CI related changes",
      "emoji": "🎡",
      "value": "ci"
    },
    "docs": {
      "description": "Documentation only changes",
      "emoji": "✏️",
      "value": "docs"
    },
    "feat": {
      "description": "A new feature",
      "emoji": "🎸",
      "value": "feat"
    },
    "fix": {
      "description": "A bug fix",
      "emoji": "🐛",
      "value": "fix"
    },
    "perf": {
      "description": "A code change that improves performance",
      "emoji": "⚡️",
      "value": "perf"
    },
    "refactor": {
      "description": "A code change that neither fixes a bug or adds a feature",
      "emoji": "💡",
      "value": "refactor"
    },
    "release": {
      "description": "Create a release commit",
      "emoji": "🏹",
      "value": "release"
    },
    "style": {
      "description": "Markup, white-space, formatting, missing semi-colons...",
      "emoji": "💄",
      "value": "style"
    },
    "test": {
      "description": "Adding missing tests",
      "emoji": "💍",
      "value": "test"
    }
  }
}
复制代码

这种 commit 不需要额外添加强制校验commit的工具，这个格式因为表情是属于 subject 字段的，所以是符合 angluar 规范的，默认用 angluar 的校验是可以通过的。所以有的人想要表情commit是用 commitizen+git-cz 实现的。

表情在提交信息最开头显示

这里，我先介绍一个 commitizen 官网推荐的一个适配器 cz-emoji，但我这个主题不是讲它。它提交的commit信息如下：

cz-emoji：这个适配器是将type部分替换成emoji了。由于这个比较简单，大家感兴趣去看它的官网说明吧，这里不讨论如何使用这个了。

好了，这里主要讲如何在 angluar 基础上加入表情，保留type的情况，在type前面加入表情 :emoji:（这个是我自己搞了好半天的😂）。这个commit规范就是我上面提到的表情开头规范

来吧，先让俺们安装 cz-customizable

npm i -D cz-customizable
复制代码

package.json

"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}
复制代码

cz-customizable：这个是适配器用于自定义 cz 命令的，可以自定义提示信息、types、长度等等。

在项目根目录下添加 .cz-config.js 添加配置项即可，大家可以参考官网说明配置属于自己项目的提示和规则，我的配置文件如下：

/.cz-config.js

module.exports = {
  types: [
    {
      value: 'feat',
      name: 'feat: 新功能'
    },
    {
      value: 'fix',
      name: 'fix: 修复bug'
    },
    {
      value: 'init',
      name: 'init: 初始化'
    },
    {
      value: ':pencil2: docs',
      name: 'docs: 文档变更'
    },
    {
      value: 'style',
      name: 'style: 代码的样式美化'
    },
    {
      value: 'refactor',
      name: 'refactor: 重构'
    },
    {
      value: 'perf',
      name: 'perf: 性能优化'
    },
    {
      value: 'test',
      name: 'test: 测试'
    },
    {
      value: 'revert',
      name: 'revert: 回退'
    },
    {
      value: 'build',
      name: 'build: 打包'
    },
    {
      value: 'chore',
      name: 'chore: 构建/工程依赖/工具'
    },
    {
      value: 'ci',
      name: 'ci: CI related changes'
    }
  ],
  messages: {
    type: '请选择提交类型(必填)',
    customScope: '请输入文件修改范围(可选)',
    subject: '请简要描述提交(必填)',
    body: '请输入详细描述(可选)',
    breaking: '列出任何BREAKING CHANGES(可选)',
    footer: '请输入要关闭的issue(可选)',
    confirmCommit: '确定提交此说明吗？'
  },
  allowCustomScopes: true,
  allowBreakingChanges: ['feat', 'fix'], // 当提交类型为feat、fix时才有破坏性修改选项
  subjectLimit: 72
};

复制代码

现在输入 cz 或 git cz ，效果如下：

因为，我想要表情开头，所以我用了个取巧的办法将 .cz-config.js 的 types 字段修改为下面这个样子来实现：

types: [
    {
      value: ':zap: feat',
      name: '⚡ feat: 新功能'
    },
    ...
]
复制代码

效果如下，就是加入了表情部分，其它跟上面那个效果一样，就不录gif图了：

将value部分绑定上表情码就会带上表情了，用表情码 :zap: 不用⚡ 是因为之后咱们还需要加入校验commit信息，校验表情的预设只有是表情码能通过校验。咱们自定义这种格式是不符合 angluar 规范的，需要安装其他校验工具。马上就要讲到啦！

这里的表情都是用的 gitmoji 里提供的表情，以及后面强制校验commit信息表情也是校验是否包含在这个里面的表情。这个表情码在命令行中显示的还是表情码，提交到 github 上面后就会显示对应的表情的。如下图：

vscode提交代码工具

可能你懒得敲命令去提交commit，这里推荐两个我个人觉得还可以的vscode提代码的插件，直接在扩展商店里搜了安装就行，用法很简单就不说，大家下载的时候读一下 Usage 就会了。（之后我会自己写一个符合自己commit习惯的vscode插件，到时候推荐给大家）😁

Visual Studio Code Commitizen Support：这个插件是我一直用习惯了的，它遵循cz-customizable并创建所需的配置文件，如果你的项目根目录有 .cz-config.js 配置，它会根据这个配置文件显示提示和校验规则（需要重启下vscode才会生效）。此插件提交效果如下：

Conventional Commits：这个插件可以填表情(选填)，格式是符合 angluar 或 angluar+subject加表情规范的。此插件提交效果如下：

规范校验

上面提代码的工具，虽然可以让大家方便的提代码，but！如果你们团队的人就是不遵守规范提代码怎么办呢？是时候请出 husky commitlint 登场啦！他们可以在你commit的时候校验你的commit信息是否是规范的，如果不是就提交不了。

这部分，也是分为 angluar版和自定义表情版展开，首先，不管说明版本都需要安装这两个工具：

husky：顾名思义，哈士奇，哈哈，咬住你不放。这个工具是用来在git钩子里运行命令有问题咬住你过不去钩子的。一般用来执行eslint、run test、commitlint 相关命令的。

commitlint：这个就没啥好说的了，就是校验你的commit信息的，提供多种共享配置。

Commit message 校验

首先，下载 husky & commitlint。

npm i -D husky commitlint
复制代码

新建一个 .commitlintrc.js 或 commitlint.config.js。commitlint会找到这个文件，按文件中指定的 extends 去校验 commit 信息。也可以自定义设置一些规则。

angluar 版

校验 angluar commit规范信息的，内容如下：

/.commitlintrc.js

module.exports = {
  extends: ['@commitlint/config-conventional']
};
复制代码

@commitlint/config-conventional是按 angluar 规范校验的，大家也可以用其他的，或者自己写一个lint发到npm上。

emoji 开头版

校验我上面提的 emoji 开头的commit规范信息，commitlint 并没有内置合适的共享配置，这种需要自己写一个符合的配置，好在已经有人写过这种可共享配置了，这里我用的网上找到的空谷大佬写好的 commitlint-config-gitmoji。

npm i -D commitlint-config-gitmoji
复制代码

内容如下：

/.commitlintrc.js

module.exports = {
  extends: ['gitmoji']
};
复制代码

commitlint都设置好了，下面我们要实现提交时强制校验。

husky强制校验commit信息

执行以下命令，会在项目根目录下生成一个.kusky文件夹。（这里默认大家下的husky都是最新的5.0版本）

npx husky install
复制代码

在.husky文件夹内创建commit-msg文件（注意不要建到husky/_那个文件夹里去了），内容如下：

#!/bin/sh

npx --no-install commitlint --edit "$1"
复制代码

这个时候，我们再提交代码的时候会走到commit-msg这个钩子里，执行我们写好的校验commit的命令，当commit信息不符合规范时，commitlint会提示哪里规则不对，husky会拦住当前commit信息提不上了。就实现了强制遵守定义好的commit规范，不能随便瞎提代码了！！！

下面，我们再聊下在commit之前校验代码和跑测试。

代码规范校验 & 跑测试

虽然咱们编辑器都有eslint插件自动修复代码，大家一般也都不会提交不符合eslint的代码，但是有的同学可能真的不装这个插件没有自动修复，不看效果盲写代码提交的，所以以防万一都是需要在commit前校验代码规范以及测试的，这样保证你提的代码都是正儿八经的符合规范的并且通过测试的🤣，哈哈哈哈！！！

首先，咱们需要安装 lint-staged，很多人不用 lint-staged，直接在 pre-commit 钩子里执行 npm run lint，这样有个问题，如果项目大了，你只修改一个文件，但它仍然会校验src下所有文件，就会导致提个代码慢的要死等半天。而 lint-staged 就能解决这个问题，它只会校验你修改的那部分文件。好了，了解前因后果后我们开始吧~

npm i -D lint-staged
复制代码

package.json

"scripts": {
  "lint": "vue-cli-service lint --fix",
  "test": "your-cmd" 
},
"lint-staged": {
  "src/**/*.scss": [
    "stylelint --fix"
  ],
  "src/**/*.{js,vue,ts,tsx}": "npm run lint"
}
复制代码

在.kusky文件夹内创建pre-commit文件，内容如下：

#!/bin/sh

npx --no-install lint-staged

npm run test
复制代码

在这里，当你提交代码就会自动校验并修复你的所提交的代码。下面，我们开始讲 CHANGELOG 自动生成。

CHANGELOG 自动生成

CHANGELOG 大概的样子长这个样：

首先，聊一下什么是 CHANGELOG ，为什么需要 CHANGELOG ？它记录你项目所有的commit信息并归类版本，可以快速跳转到该条commit记录，甚至可以显示修改人信息一眼发现bug的创建者😂。它能让你方便知道项目里哪个版本做了哪些功能有哪些bug等信息。也方便排查bug，对于提交记录一目了然，不用一个一个去翻去查。

这里，就直接用 standard-version 来实现自动生成 CHANGELOG 了。 conventional-changelog 咱们就不聊了，毕竟是它推荐咱们用 standard-version （这都是同一个团队的东西，基于conventional-changelog实现的）。关于为什么推荐 standard-version，大家自行阅读官方解释吧！官方地址给大家。

semantic-release 也不聊了，因为 CI/CD 我没咋研究过，没法聊😂！官方地址在此，还有一篇推荐文章大家有兴趣的可以读读。

好了，我们开始用 standard-version 来实现吧！先来下载~

npm i -D standard-version
复制代码

package.json

{
  "scripts": {
    "release": "standard-version"
  }
}

复制代码

执行以下命令，就会根据你的commit信息自动生成 CHANGELOG.md 文件。

npm run release
复制代码

当你的commit type是 feat和fix的时候执行这个命令，它会自增版本号。

这里说个我调试中发现的小问题，在你执行过一次后如果你删掉了 CHANGELOG.md 文件，并且没有再修改提交，再重新去执行生成命令，它会给你生成只有一个版本号信息的文件，你必须提交一下再执行才会有commit日志，但在这个提交之前的那些记录不会再显示（很奇怪，调试的时候注意下这个问题）。

standard-version 提供自定义配置不同类型对应显示文案，在根目录新建 versionrc.js 文件，这里我示例一个我的 versionrc.js 内容：

module.exports = {
  "types": [
    { "type": "feat", "section": "✨ Features | 新功能" },
    { "type": "fix", "section": "🐛 Bug Fixes | Bug 修复" },
    { "type": "init", "section": "🎉 Init | 初始化" },
    { "type": "docs", "section": "✏️ Documentation | 文档" },
    { "type": "style", "section": "💄 Styles | 风格" },
    { "type": "refactor", "section": "♻️ Code Refactoring | 代码重构" },
    { "type": "perf", "section": "⚡ Performance Improvements | 性能优化" },
    { "type": "test", "section": "✅ Tests | 测试" },
    { "type": "revert", "section": "⏪ Revert | 回退" },
    { "type": "build", "section": "📦‍ Build System | 打包构建" },
    { "type": "chore", "section": "🚀 Chore | 构建/工程依赖/工具" },
    { "type": "ci", "section": "👷 Continuous Integration | CI 配置" }
  ]
}
复制代码

配置之后，我的 CHANGELOG 就长这个样子啦！

这里得提一下， standard-version 默认的预设是 angular ，像咱们之前自定义表情那种commmit，规范和angular不一样，它读不到对应的type生成的更改日志是没法分类的，上面写 commitlint-config-gitmoji 工具的大哥已经写了根据 :emoji: type: … 格式生成 CHANGELOG 的工具conventional-changelog-gitmoji-config了，这里咱们就直接用吧！不过这个工具并没有提供自定义配置类型文案的功能，在源码里写死了，所以用了这个工具不能像上面那样 versionrc.js 自定义了，不过它自带的也挺好看的，可以设置显示表情，还支持中英文两种，还支持显示修改人和邮箱，也是很强大的！！！🉑

来，咱们下载先~

npm i -D conventional-changelog-gitmoji-config
复制代码

standard-version 通过 --preset 命令另外指定预设（源码内发现）

{
  "scripts": {
    "release": "standard-version --preset gitmoji-config"
  }
}
复制代码

这里解释一下，为什么 --preset gitmoji-config 就可以读到预设，这个包明明叫 conventional-changelog-gitmoji-config 啊，这是因为 conventional-changelog-preset-loader找预设时找的是 conventional-changelog-xxx，前缀是写死的 conventional-changelog-，源码截图在此：

CI/CD没搞过，也没用上 standard-version，为了方便我就直接在 pre-push 钩子里执行生成 CHANGELOG 的命令了哈~

.husky/pre-push

#!/bin/sh

npm run release
复制代码

这样，当我执行 git push 的时候，就会自动生成 CHANGELOG.md 一并提交到远端了，就不用手动执行 npm run release 命令再push了。啦啦啦🎈🎈🎈

终于结束啦！感谢大家听我啰嗦了这么久，希望可以帮到大家，如果文章中有错漏之处还望指正。谢谢大家啦！！！😜

参考文献

Angular官方comit规范说明

百度到的素不相识空谷先生的语雀文章

优雅的提交你的 Git Commit Message

朋友的博客

以及文中各个工具的文档和源码，就不一一罗列了

commit规范+commitlint+CHANGELOG自动生成一条龙服务

前言

Commit 规范说明

Angluar commit message 规范

Header部分

Footer部分 选填 可以包含以下两种情况

自定义 commit message 规范

Commit 规范工具

Angluar 规范版

表情在subject部分开头的显示

表情在提交信息最开头显示

vscode提交代码工具

规范校验

Commit message 校验

代码规范校验 & 跑测试

CHANGELOG 自动生成

参考文献

Footer部分选填可以包含以下两种情况