企业官网建设流程全解析

1. 为什么前端团队需要自动化 changeLog

先说结论：changeLog不是给领导看的装饰品，它是团队协作的“时间轴”。当项目迭代到第 30 个版本，有人问“这个fix到底修了哪个线上问题”，如果只能靠翻 git log 一条条猜，那基本等于没有记录。前端项目尤其明显，package.json里的版本号天天变，但CHANGELOG.md往往还停留在“初始化项目”那一行。

我见过太多团队的做法是：发版前手动回忆这周改了啥，然后写一段“修复若干问题、优化部分体验”。这种 changeLog 对排查问题毫无价值。真正有用的 changeLog 应该由git-commit规范驱动，提交信息写对了，工具自动帮你归类成feat、fix、perf这些区块，版本号也能按语义化规则自动递增。

这篇要打通的就是这条链路：从commitlint约束提交格式，到conventional-changelog生成日志，再到standard-version一键完成“升版本 + 打 tag + 写 CHANGELOG”。适合正在做前端工程化、准备落地规范化发布流程的同学。下面所有配置都可以直接复制，最后会用一个真实提交验证整条链路跑通。

2. 前置准备：TaoToken 与项目环境

在动手之前，先把两件事准备好：一个是模型能力入口，一个是本地 Node 环境。

如果你在配置过程中遇到报错，或者想让模型帮你解释某段commitlint规则、生成一份standard-version配置骨架，可以直接用 TaoToken 的模型对话能力来辅助排查。它的入口是https://taotoken.net/api，配合 API Key 就能在脚本或工具里调用。对于长期做前端工程化、需要反复调试配置的团队，Coding Plan 会更划算，适合把这类“配置 + 排障”的重复动作沉淀成固定流程。

本地环境要求不高：

• Node.js 16 以上（standard-version对 Node 版本有要求，太低会报optional chaining语法错误）
• 项目已经用 git 管理，并且至少有一次提交
• 包管理器用 npm / yarn / pnpm 都行，下面统一用 npm 演示

先确认 git 状态干净，避免生成 changeLog 时把未提交的改动混进去：

git status git log --oneline -5

如果git log里全是“update”“fix bug”这种提交，别急，后面会先立规矩再生成。

3. 可复制配置：commitlint + standard-version 骨架

3.1 安装依赖

一次性把需要的包装上。这里分两类：提交规范类和日志生成类。

npm install --save-dev \ @commitlint/cli \ @commitlint/config-conventional \ husky \ conventional-changelog \ conventional-changelog-cli \ standard-version \ conventional-changelog-gitmoji-config

简单说下各自职责：@commitlint/cli+config-conventional负责校验提交信息；husky把校验挂到 git hook 上；conventional-changelog-cli负责生成日志；standard-version负责升版本、打 tag、写 CHANGELOG 一条龙；conventional-changelog-gitmoji-config是给喜欢 emoji 前缀的团队用的预设。

3.2 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], 'header-max-length': [2, 'always', 100] } };

type-enum就是允许的提交类型白名单。subject-case关掉是因为中文提交信息经常被这条规则误伤。header-max-length限制标题长度，避免有人写一整段话。

3.3 husky 挂载 commit-msg 钩子

初始化 husky 并添加钩子：

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

执行完会在.husky/下生成commit-msg文件。之后每次git commit，commitlint 都会先校验信息格式，不合格直接拒绝提交。这一步是整条链路的“守门员”，没有它，后面的 changeLog 就是无源之水。

3.4 standard-version 配置

在package.json里加脚本，同时新建.versionrc文件控制生成行为。

package.json的scripts部分：

{ "scripts": { "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s", "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0", "release": "standard-version", "release:gitmoji": "standard-version --preset gitmoji-config -i CHANGELOG.md --header '# 更新日志'" } }

.versionrc配置：

{ "types": [ { "type": "feat", "section": "新功能" }, { "type": "fix", "section": "问题修复" }, { "type": "perf", "section": "性能优化" }, { "type": "refactor", "section": "代码重构" }, { "type": "docs", "section": "文档更新" }, { "type": "style", "section": "代码格式" }, { "type": "test", "section": "测试相关" }, { "type": "build", "section": "构建依赖" }, { "type": "ci", "section": "持续集成" }, { "type": "chore", "section": "其他改动" }, { "type": "revert", "section": "版本回滚" } ], "releaseCommitMessageFormat": "chore(release): 发布 v{{currentTag}}" }

types决定了 CHANGELOG 里每个区块的中文标题。releaseCommitMessageFormat是standard-version自动提交时的信息模板，{{currentTag}}会被替换成新版本号。

注意：conventional-changelog -p angular只会识别fix、feat、perf这几类提交，其他类型默认不写入日志。如果你想让refactor、docs也出现在 CHANGELOG 里，需要用.versionrc配合standard-version，或者自定义 preset。

4. 验证请求：从一次提交到生成 CHANGELOG.md

配置写完，必须跑一遍完整链路，否则你永远不知道是配置错了还是提交格式错了。

4.1 先做一次规范提交

改一个文件，然后按规范提交：

git add . git commit -m "feat: 新增用户登录页表单校验"

如果 commitlint 配置生效，这条提交会通过。故意写一条不合规的试试：

git commit -m "update login"

你会看到类似subject may not be empty或type must be one of [...]的报错，提交被拒绝。这说明守门员在工作。

4.2 生成 CHANGELOG

先跑一次只追加最新内容的命令：

npm run changelog

打开CHANGELOG.md，应该能看到类似结构：

### Features * 新增用户登录页表单校验 ### Bug Fixes * 修复列表分页参数丢失问题

如果想把历史所有提交都生成一遍，用：

npm run changelog:all

-r 0表示从第一个版本开始重新生成，适合第一次接入时补全历史记录。

4.3 用 standard-version 一键发布

确认 CHANGELOG 内容没问题后，执行：

npm run release

这条命令会做四件事：根据提交类型自动决定版本号（feat升 minor，fix升 patch）、更新package.json版本、生成/更新CHANGELOG.md、创建一个 release commit 并打上 git tag。

如果团队用 emoji 前缀，改用：

npm run release:gitmoji

它会用gitmoji-config预设解析带 emoji 的提交，并自动把# 更新日志作为文件头。

4.4 验证结果

git log --oneline -3 git tag cat CHANGELOG.md

你应该能看到新的 tag（比如v1.1.0）、release commit，以及 CHANGELOG 里新增的区块。到这一步，整条链路就算跑通了。

5. 本篇常见错排查

5.1 提交了但 CHANGELOG 没内容

最常见的原因就一个：提交信息不符合规范。conventional-changelog只认type: subject这种格式，fix : 🐛 bug修改里冒号前有空格、emoji 在 type 后面，都会导致解析失败。正确写法是fix: 修复登录态丢失，emoji 可以放在 subject 里，但不要放在 type 和冒号之间。

另一个原因是只生成了fix、feat、perf。如果你提交的是docs或chore，默认不会出现在日志里。解决办法是用standard-version配合.versionrc，它会把所有配置的类型都写进去。

5.2 commitlint 报错但不知道哪条规则

把报错信息完整看一遍，通常会指出具体规则名。比如type-enum就是类型不在白名单，subject-empty就是冒号后面没写内容。临时想跳过校验可以用git commit --no-verify，但只建议在紧急修复时用，别养成习惯。

5.3 standard-version 版本号不符合预期

版本号由提交类型决定：有feat升 minor，只有fix升 patch，有BREAKING CHANGE升 major。如果生成的版本号不对，先检查最近一次 tag 到现在的提交里有没有feat。另外，如果本地 tag 和远程不一致，standard-version可能算错基线，先git fetch --tags同步一下。

5.4 emoji 提交无法识别

conventional-changelog默认不识别 emoji 开头的提交。两个方案：一是提交时把 emoji 去掉，只保留type: subject；二是用conventional-changelog-gitmoji-config预设，它专门处理feat: xxx这种格式。VS Code 插件生成的提交如果带 emoji，记得在设置里关掉 emoji 展示，或者改用 gitmoji 预设。

5.5 husky 钩子不生效

检查.husky/commit-msg文件是否有执行权限，以及package.json里有没有"prepare": "husky install"。如果是新克隆的项目，先跑一次npm install触发 prepare，再手动npx husky install。

6. 把模型能力接进你的发布流程

配置跑通之后，日常发版就是npm run release一条命令。但团队里总有人提交信息写不规范，或者你想让模型帮忙把一堆零散提交归纳成一段人话版的 release note，这时候可以接 TaoToken 的 API。

具体做法是在项目里加一个脚本，读取git log最近一段提交，调用模型接口生成摘要，再追加到 CHANGELOG 顶部。API 地址用https://taotoken.net/api，Key 在控制台的 API Keys 页面创建。如果你只是偶尔用，模型对话页面就够；如果要把这个动作固化到 CI 里，Coding Plan 更适合长期跑。

接入文档里有完整的请求示例和参数说明，照着改一下model和messages就能用。这样你的 changeLog 就不只是提交记录的堆砌，而是带归纳、带上下文的发布说明。整条链路从 commit 规范开始，到自动生成结束，中间不需要人工回忆任何东西。