企业官网建设流程全解析

1. 为什么非要把commit规范和CHANGELOG绑在一起

我接手某老项目的时候，git log简直没法看。翻出来全是"fix bug"“update”“修改问题”“commit”这种信息，短的看不懂，长的像小作文。更要命的是，产品上线要写变更说明，只能翻提交记录一条条猜哪个改动对应哪个功能，猜错了又得回头改。后来我把整个git历史输出成日志瞄了一眼，头都大——同一个功能拆了一百多次提交，日期、作者、文件全都搅在一起。

那会儿我就意识到，commit message不是写给电脑看的，是写给一个月之后的自己和同事看的。可光靠"自觉"根本撑不住，得靠工具把格式卡死。而且规范真正的红利不在于提交消息本身好看，而在于它能把"代码变更"自动变成"人能读懂的版本说明"。这就要聊到Conventional Commits这套约定——它本质上是给commit message定了三个要素：type（提交类型）、scope（影响范围）、subject（简明描述），再加可选正文和脚注。只要消息按这个约定写，后续的CHANGELOG生成、版本号自动推断、代码审查过滤全都能自动化，等于一次规范投入，后面每条流水线都在复用。

现在很多团队都在推git commit规范，但只停在"让提交消息整齐"这一层，忽略了和CHANGELOG联动这件事。其实两者绑在一起才是收益最大的：规范约束提交格式是源头，CHANGELOG自动生成是终点，中间靠工具链自动衔接，人工只负责写好type和描述，剩下版本号、日期、变更归类、tag推送全都自动化。这篇文章我把整套配置拆开讲清楚，从钩子拦截到版本发布一条龙，适合正在被混乱提交记录折磨的团队，也适合准备从零规范仓库的人参考。

2. 先搞清楚工具链里每个环节在干什么

2.1 提交规范只是起点，真正的终点是版本变更记录的自动产出

只做"提交格式校验"其实很简单，难的是把规范提交和版本变更记录串成一条自动化的链路。整个链路要有四样东西配合：校验工具、提交流程辅助工具、git钩子、变更日志生成器。每样工具解决一个环节的问题，缺一个都会回到手动整理的老路。

链条大概是这样的：开发者写代码 -> 交交互式问答自动拼出规范消息 -> 提交时git钩子校验消息格式 -> 格式不对直接拦截 -> 格式通过后进入仓库历史 -> 发布时变更日志工具扫描历史，按类型分类生成CHANGELOG -> 同时自动提升版本号、打tag。整个过程只有第一步和最后一步涉及人工确认，中间没有任何人肉干预。

我第一次搭这套链路时最大的误区，是以为commitlint一个工具就够了。实际上commitlint只管"消息写得不规范就拒绝提交"，它不管你怎么写出规范的消息。如果团队里有人不喜欢交互式问答，手写信息写得残缺不全，commitlint会拦截但体验很差。所以必须配套一个能让开发者轻松写出合规消息的工具，这个工具负责把"我想提交一个修复功能"翻译成"fix(模块): 描述"。再加上husky把校验挂在git提交前自动执行，这套闭环才算成立。

2.2 每件工具的定位和选型理由

先说commitlint，它负责校验commit message格式。为什么选它而不是自己写正则？因为commitlint的规则引擎很成熟，支持继承知名规范（比如@commitlint/config-conventional），还能自定义规则，比如限制每个type必须用英文、subject不能超过72个字符、footer里必须有关联issue编号。如果自己写shell脚本做校验，刚开始还行，规则一多就是灾难。

再说commitizen，它提供交互式问答来生成规范消息。不习惯的人可能会觉得多余，但它解决的是"凭脑子记格式"的问题。交互式问答会逐步问你：这次改动的类型是feat还是fix？影响范围是哪个模块？描述是什么？有没有破坏性变更？回答完就自动拼出一条合法的commit信息。选commitizen还有一个理由：团队中新人上手时基本零学习成本，不用死记硬背type分类。

husky负责把钩子脚本挂到git生命周期里。老版本的husky是在package.json里写"husky": {"hooks": {...}}，新版8之后改了做法，直接生成.husky目录下的脚本文件。这里必须吐槽一下，网上很多教程还是旧版做法，按着配会发现新版根本不生效。后面我会给出新版的配置方式，这条细节特别容易踩坑。

最后是standard-version和conventional-changelog。conventional-changelog是底层库，standard-version是封装好的一键发布命令。它会自动读取git历史里符合Conventional Commits的消息，归类到新版本，生成或追加CHANGELOG.md，然后自动升级package.json和package-lock.json里的版本号，提交并打上git tag。我用standard-version而不是直接用conventional-changelog的API，是因为它把版本号推断、提交、打tag全串好了，命令行一条命令就跑完。

四样工具的作用我列在下面这张表里：

每个工具都是链条里不可拆的一环，省掉哪个，后面的自动化都会断掉。

3. 一步步配置完整提交链路

3.1 初始化npm项目并安装依赖

先保证当前目录是npm项目，没有就先初始化。我习惯在项目根目录执行：

npm init -y

然后安装所有依赖。这里注意区分依赖类型：husky、commitlint这类属于开发依赖，放到devDependencies；standard-version建议也放devDependencies，因为它只是工程辅助工具，不应该打进生产包里。

npm install --save-dev husky commitlint @commitlint/cli @commitlint/config-conventional commitizen cz-conventional-changelog standard-version

安装完检查node_modules是否正常下载。我在某次配置中遇到npm源延迟，husky的脚本没完全写入，后面执行钩子命令一直报错。如果网络环境不太稳，建议装完之后跑一下npm ls husky确认版本已经落位。

3.2 初始化husky钩子并创建commit-msg脚本

husky 8之后的初始化方式比之前简单直接。先激活git hooks目录指向，再创建我们需要的那两个钩子：

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

执行完，项目根目录会多出.husky文件夹，里面至少有一个commit-msg文件。这个文件里的$1是git传给钩子的提交信息文件路径，commitlint靠它读取那段临时存储的commit message。注意\$1在shell里是转义过的，不要手贱把它改成普通$1，否则shell在创建脚本的时候就会把变量展开掉，钩子实际执行时读到的就是空值。

然后新建或编辑.husky/commit-msg，确认内容如下：

npx --no -- commitlint --edit $1

这里有个细节：--no是告诉npx不要自动安装某个缺失的包，避免在钩子执行时联网下载依赖，导致提交变得很慢甚至失败。没加--no的话，如果某台机器上node_modules缺失，npx会自作主张去下载，这在CI环境里尤其致命。

我还会顺手加一个pre-commit钩子，用于在提交前跑lint或测试。这个钩子是npx husky add .husky/pre-commit "npm run lint"。不过要注意，如果项目里还配置了lint-staged来只检查暂存区文件，这两个工具的优先级和冲突问题我在后面专门展开讲。

3.3 配置commitlint规则

在项目根目录创建commitlint.config.js：

module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [2, 'always', [ 'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert' ]], 'subject-case': [0], 'body-max-line-length': [0] } };

extends继承的是社区最常用的Angular提交规范。type-enum限定了允许的提交类型，任何不在列表里的type都会导致提交被拒。我把subject-case关掉了，因为团队里有人习惯用中文写描述，全大写或全小写的强制校验反而碍事。body-max-line-length也关掉，有些改动说明很长，一行超过100字很正常，没必要为了换行拆得七零八落。

这些规则背后是commitlint的提示信息，每次被拦截的时候，它会明确告诉你是哪个规则命中了，比如"type must be one of [feat, fix, docs, ...]"。之前我遇到过同事故意写大写FEAT，结果一直被拒，后来才知道commitlint对type做了大小写敏感匹配。如果想兼容大小写，可以给type-enum的value打个补丁，用数组同时放小写和大写，但不推荐——规则就是规则，一致性能减少很多心智负担。

3.4 配置commitizen的交互式问答

commitizen本身只是一个胶水层，具体问答规则由cz-conventional-changelog这个适配器提供。在package.json里增加config字段：

{ "scripts": { "commit": "cz" }, "config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } } }

之后提交代码就不用git commit了，而是运行npm run commit。它会出现一个交互面板，一层层问：提交类型、影响范围、简要描述、详细描述、是否有破坏性变更、关联的issue编号。回答完自动拼接出完整commit message。

这里我想多说一句：commitizen不是必须的，但非常推荐。很多老手直接手写消息也能合规，但团队中总有记不住规范的人，交互式问答等于把规范内嵌到流程里，不想记也能遵守。我见过一些团队安装后觉得"麻烦"又卸载了，结果回到手写之后commitlint不厌其烦地拦截，效率反而更低。

3.5 配置standard-version

在package.json里增加脚本和配置：

{ "scripts": { "release": "standard-version", "release:minor": "standard-version --release-as minor", "release:major": "standard-version --release-as major" } }

standard-version默认按语义化版本（SemVer）从git历史推断类型：有BREAKING CHANGE就升major，有feat就升minor，只有fix或chore就升patch。如果你希望更严格地控制发布节奏，可以用--release-as强制指定这次要升的版本级别。比如功能开发周期里攒了一堆改动，但产品决定下个版本只发一个minor，就可以用npm run release:minor。

还可以在package.json里加standard-version的专属配置块，指定CHANGELOG的开关、是否跳过commit/tag等：

{ "standard-version": { "t": "v%s", "skip": { "commit": false, "tag": false, "changelog": false } } }

t是tag的前缀格式，v%s会生成v1.2.3这种tag。skip可以用来在私有包或内网项目中跳过commit和tag，有些场景只需要生成CHANGELOG文件，不希望在发布流程里自动改package.json版本。但我们要做的是标准发布链路，所以三个都设false。

3.6 commitlint对husky的依赖关系，以及钩子路径的坑

commitlint要生效，依赖husky触发了commit-msg钩子。而husky 8之后，git hooks的执行路径指向了项目根目录下的.husky目录。有个很隐蔽的问题：如果项目是用git submodule管理的，或者通过软链接共享仓库，husky在子模块里执行时可能找不到根目录的配置。我自己遇到过一次：子模块内的commit-msg钩子里写死了相对路径导致commitlint.config.js读取失败，后来改成从父仓库继承配置才解决。

另外，.husky目录里的脚本默认不会被git跟踪（新版husky会在.gitignore里加入.husky/_），但钩子脚本本身应该提交到仓库里。所以初始化完hooks后，记得把.husky/commit-msg和.husky/pre-commit加入git版本管理，这样别的同事clone下来就能直接用。

提示：如果clone仓库后执行git commit发现钩子没生效，十有八九是没跑npm install，或者项目里旧版husky的钩子脚本还残留在.git/hooks目录。删掉.git/hooks下所有带后缀的示例文件，重新执行npx husky install即可。

4. 从提交代码到发布新版本的完整演练

4.1 一次标准的修复流程会经过哪些拦截

假设现在要修复某模块登录超时的问题。先改代码，然后正常暂存：

git add src/login.js npm run commit

交互式问答里选fix，scope填auth，描述写"修复登录超时导致会话提前失效"。确认提交时，husky会触发生成的commit信息校验，commitlint检查通过，提交成功。这一步能直观看出规范的价值：提交信息里既能看到改动范围是auth，又能知道这次是为了修bug而不是加功能。

如果手写消息绕过commitizen，比如直接git commit -m "修复登录"，commit-msg钩子会毫不留情地拦截，提示type必须符合枚举。有些人嫌烦，觉得"我就是改个小问题，至于吗"。但我的看法是，这个拦截恰恰是规范落地的保障。规矩一旦建立就不能开口子，否则慢慢就形同虚设了。

4.2 用standard-version生成CHANGELOG并自动升级版本

当攒够了本次发布的功能和修复，执行：

npm run release

standard-version会做这么几件事：

1. 读取git历史里符合约定格式的提交，归类为Features、Bug Fixes、Performance Improvements等分组。
2. 根据是否有breaking change或feat，自动决定x.y.z的哪一位需要递增。
3. 更新package.json和package-lock.json里的version字段。
4. 生成新的CHANGELOG.md，追加到文件顶部。
5. 自动git add这些文件并提交，提交消息形如chore(release): 1.2.3。
6. 打上git tag，默认格式v1.2.3。

实际生成的CHANGELOG长这样：

# Changelog ## [1.2.3](https://example.com/repo/compare/v1.2.2...v1.2.3) (2025-11-07) ### Bug Fixes * **auth:** 修复登录超时导致会话提前失效 ([a1b2c3d](https://example.com/repo/commit/a1b2c3d)) * **payment:** 修复支付回调验签失败问题 ([e4f5a6b](https://example.com/repo/commit/e4f5a6b)) ### Features * **order:** 新增订单导出功能 ([c7d8e9f](https://example.com/repo/commit/c7d8e9f))

commit的哈希和对比链接是根据git remote地址自动生成的，前提是仓库设置了origin。如果是内网git服务器或私有部署，链接格式可能不识别，standard-version会退化成纯文本形式，不影响整体使用。

第一次跑release之前，建议先提交这个commit的代码并确保工作区干净。如果还有未提交的改动，standard-version会把release commit连同工作区改动混在一起，后面想单独回退发布提交就很难看。我踩过这个坑，所以每次发版前会先跑git status确认干净再执行release。

4.3 交互式问答和手工直写的实际体验对比

用npm run commit和直接git commit -m对比，最直观的区别是"错误成本"。交互式问答把type限定在可选列表里，思路是引导，不回填就不会提交；手写则完全依赖人的记忆和自律。团队十个人里只要有两个人随便写，commitlint就会频繁拦截，拦截多了大家就不耐烦。交互式问答能极大降低这种摩擦，但它不是万能的——如果有人坚持用git commit绕过，commitlint依然能把住最后一道关。所以两个工具不是替代关系，是互补关系。

4.4 生成结果的验证方法

release之后，打开package.json确认version字段已经变更，git log里能看到一条新的release提交，git tag能看到新增的tag。CHANGELOG.md里有没有漏掉某个feat？快速验证的办法是手动翻一下git log和CHANGELOG的差异：比如git log --oneline v1.2.2..v1.2.3，对比该区间内提交和CHANGELOG里的条目。如果发现漏了，很可能是提交时type用错了，比如把新功能写成了chore，standard-version就会把它归到"其他"分类里。这时候补方法就是修改那条提交的消息，或者干脆接受漏掉的结果——我的建议是按规范严格修正，否则自动化就逐渐回归手工核查了。

5. 版本号推断逻辑和project版本节奏的控制

5.1 standard-version如何从提交记录判断该升级哪一位

standard-version内部读取的是commit message里type和BREAKING CHANGE标记。判断规则可以理解成：

• 存在BREAKING CHANGE脚注，或者type后面带!，升级major。
• 存在feat提交，升级minor。
• 其他类型如fix、perf、refactor，升级patch。

实际操作中要注意一件事：initial release或者0.x阶段的版本号升级逻辑。如果项目版本号统一从0.1.0开始，发布第一条feat时，standard-version默认还会继续走0.x的逻辑，不会直接跳到1.0.0。很多团队不理解这为什么，其实是因为SemVer规定0.x阶段任何改动都可能产生破坏性变化，所以minor和patch的语义被压缩了。如果想要尽快脱离0.x初始化阶段，可以在第一次release时手动指定--release-as 1.0.0，后续就回归自动推断。

5.2 私有包和内网项目如何控制自动commit和tag

有些项目不是发布到公网npm，而是内部组件库或后端服务。这些项目其实不需要发到registry，但CHANGELOG还是很有价值，方便追踪需求和缺陷修复。这种情况下，可以在standard-version配置里把skip.commit和skip.tag设为true：

{ "standard-version": { "skip": { "commit": true, "tag": true } } }

这样执行release时，它只生成CHANGELOG.md并更新package.json的version，不会自动git提交，也不会打tag。你拿到这些变更后，可以自己决定何时提交、如何走企业内部的发布流程。这样既保留了自动整理变更日志的能力，又避免工具擅自替团队做发布决策。

5.3 从0.1.0到1.0.0之间的一些注意点

版本号切到1.0.0是一个信号，意味着对外承诺API开始稳定。如果团队里还没有稳定的对外API，我建议版本号停在0.x，让standard-version以0.x逻辑继续跑。正式对外提供能力时再切1.0.0。这里有个小技巧：如果想在某个里程碑强制升到1.0.0，可以创建一条type为feat、footer带BREAKING CHANGE:的提交，standard-version检测到breaking change就会升major。但这需要commit message写得非常严谨，一不小心就把本来不想破坏的兼容性也标成breaking了。

6. 落地过程中最容易被忽视的几个坑

6.1 lint-staged和commit-msg钩子的执行优先级

项目里如果同时用了lint-staged，它跑在pre-commit钩子上，只对暂存区的文件做检查。commitlint跑在commit-msg钩子上，校验的是本次提交的消息。有人把这两件事搞混，以为lint-staged报错之后消息校验就不会执行了，或者反过来。实际上pre-commit在commit-msg之前执行，代码检查不过，提交直接终止，commit-msg根本轮不到。所以如果你看到消息格式没问题但提交被拒，先去查pre-commit的lint结果，很可能代码风格检查没过。

我当时第一次搭的时候，纠结了很久到底哪个钩子先执行，后来翻了git文档才确认：pre-commit阶段在commit-msg生成消息之前。这也解释了为什么commit-msg钩子拿到的是一份临时文件，而不是等开发者确认之后再生成。这个顺序容易混淆，建议大家在团队文档里写清楚。

6.2 rebase和amend对commitlint的干扰

只要改了历史提交的消息，或者合并提交，commit-msg钩子都会再次触发。比如git commit --amend改描述，如果改完格式有问题，会被commitlint拦截；git rebase -i批量改写历史时，每条消息也都会过一遍校验。这个场景下最容易出现的问题是已经有大量旧提交不符合格式，一旦触发rewrite，会被一批批拦截。

解决思路是分批处理：先把存量提交的type统一改写合格，再纳入commitlint严格模式。我自己在某历史仓库就是这么干的，老commit消息全是"wip"“fix typo”，我花了一个下午用git filter-branch把所有消息映射成fix(unknown): 原始描述，才让工具链顺利跑起来。注意git filter-branch会改写提交哈希，如果仓库已经被多人共享，一定要确认大家都能接受强制推送带来的影响。

注意：批量改写提交历史属于危险操作。在共享分支上执行之前，必须和团队确认，否则其他人的本地分支会变得乱七八糟。我建议在长期维护的公共分支上不要轻易做历史改写，宁可让工具从当前时间点开始严格执行规范，历史遗留问题慢慢接受现实。

6.3 中文提交信息是否可行

commitlint默认的subject大小写规则对中文不友好，因为中文没有大小写概念。我在上面的规则配置里关掉了subject-case，就是为了支持中文描述。实际跑下来，生成的CHANGELOG里中文描述显示得很正常，反而比英文描述更直观。不过我的建议是，scope尽量用英文（英文能准确表示模块名），subject可以用中文详细描述。例如fix(auth): 修复登录超时导致会话提前失效，type和scope保持英文，描述用中文，机器能解析，人也看得懂。这一点在很多团队里争议很大，但我实测之后觉得这个混合方式是目前最不易产生歧义的。

6.4 企业内网安装依赖失败的止损方案

内网环境装npm包经常遇到两个问题：registry不通、二进制包下载失败。husky和commitlint都是纯JS包，不太依赖二进制，但下载时如果node_modules不完整，钩子脚本执行时会直接报错。我的止损方案是：先把整套依赖在可联网机器上装好，确认node_modules完整，再整体拷贝进内网环境。或者在内网配置一个私有镜像源，把npm包缓存起来。最野的路子是不依赖husky，直接在.git/hooks里手动写校验脚本，但这样没法跟package.json的依赖版本绑定，团队协作时维护成本很高，不推荐。

6.5 package-lock.json的版本同步

跑standard-version时它只改package.json里的version，如果项目有package-lock.json且里面记录了根包版本，可能不同步。新版standard-version其实已经处理了这个问题，会一并更新lock文件。但如果你用的是旧版本，或者用了pnpm的lock文件，可能不会自动同步。发版后记得检查一下package.json和锁文件版本是否一致，否则某些严格校验的CI流程会判定lock文件过期。

7. 最后分享一点个人经验

这套commit规范我前后在多个项目里搭过，最大的感悟是：规范不应该靠人去强制，而应该靠工具自动兜底。人总会忘，工具不会。commitlint拦截格式、commitizen引导输入、standard-version自动整理、husky串起整条链路，四件事各司其职，团队只需要维护好type枚举和scope列表，其他统统交给自动化。

还要提醒一句：commit规范是"组织级约定"，不是"个人喜好"。如果有人不认同，强行推进只会让团队内耗。我自己的做法是先在小组内试运行一到两个迭代，用CHANGELOG的实际效果说服大家。等大家看到版本变更记录整整齐齐、找历史改动几秒定位的时候，规范自然就立住了。

如果你只是一个人维护仓库，这套配置照样值得上。几个月后回看自己写过的commit，能一眼看出当时改了什么、影响了哪个模块，这种连贯性是随手git commit -m "update"给不了的。