为什么前端项目一定要告别手动编写变更日志？
先聊聊手动写日志的那些“坑”，这些都是我和身边团队踩过的真实雷区。去年我帮一个做SaaS产品的朋友优化前端工程化，他们团队6个人，两周一个迭代，每次发版前都要安排一个人专门“考古”——翻Git历史记录、比对issue列表、问同事“你上次那个修复记到日志里没”，整个过程至少1小时。结果有次急着上线，日志里漏写了“修复移动端输入框错位”的关键更新，用户升级后遇到问题来反馈，团队翻了半天Git才找到对应commit，差点耽误线上问题处理。这还不是最糟的，我见过更离谱的日志：某项目CHANGELOG.md里写着“v1.2.0：修复了若干bug”，结果用户发现某个影响核心功能的bug在这个版本被意外修复了，团队却完全不记得什么时候改的，最后只能回滚代码排查。
手动维护变更日志的问题其实可以 成“三难”：耗时难省，每次发版前要人工筛选、分类、格式化commit记录；内容难全，开发时记得改了什么，发版时可能早就忘光，尤其是修复多个bug或小优化时容易遗漏；格式难统一，没有规范的话，不同开发者写的日志风格差异大，有的详细有的简略，新人更是不知道该怎么写。而在多人协作或开源项目里，这三个问题会被无限放大——想象一下，如果React或Vue的变更日志是手动写的，你觉得能找到某个API变更具体在哪个版本吗？
那自动化变更日志到底好在哪？最直观的是省时间，配置好工具后，生成日志就是一条命令的事，我现在带的团队发版时日志环节最多花2分钟；其次是格式规范，不管团队多少人，日志永远按照“Features”“Bug Fixes”“Documentation”这样的结构清晰展示；更重要的是可追溯，每个变更都能直接关联到Git commit和开发者，用户问“v3.2.0修复的登录问题具体是哪个场景”，直接点日志里的commit链接就能看到代码 diff。npm官方文档里提到，超过60%的主流前端开源项目都在用conventional-changelog或其衍生工具（链接：https://docs.npmjs.com/about-semantic-versioning，rel=”nofollow”），因为它完美契合语义化版本（SemVer）的要求，让“什么时候用patch、minor、major版本号”有了明确依据。
手把手配置conventional-changelog，3步实现日志自动生成
别担心配置复杂，我把整个流程拆成了“安装依赖→规范提交信息→配置生成脚本”三步，跟着做，即使是刚接触工程化的前端同学也能一次搞定。
第一步：安装核心依赖（5分钟搞定）
首先你需要安装几个工具：conventional-changelog-cli（生成日志的核心）、commitlint（检查提交信息格式）、husky（Git钩子，确保提交前格式正确）。打开终端，进入你的前端项目根目录，运行下面的命令：
npm install save-dev conventional-changelog-cli @commitlint/cli @commitlint/config-conventional husky这里有个小坑要提醒你：不同工具的版本兼容性可能有问题。我之前配置时直接装了最新版，结果husky 8.x和commitlint 18.x配合时总报错，后来查文档发现指定版本更稳妥（链接：https://commitlint.js.org/#/guides-local-setup，rel=”nofollow”）。如果你遇到类似问题，可以试试固定版本：npm install save-dev conventional-changelog-cli@2.2.2 @commitlint/cli@17.4.4 @commitlint/config-conventional@17.4.4 husky@8.0.3，亲测这个版本组合在Vue、React、Vite项目里都能稳定运行。
第二步：规范提交信息（关键中的关键）
conventional-changelog能自动生成日志，核心是靠结构化的Git提交信息。就像快递需要规范的地址格式才能准确送达，提交信息也需要固定格式才能被工具识别。目前最主流的是Angular团队提出的规范，结构大概是这样：type(scope): subject，比如feat(user): add profile edit function。下面这个表格整理了常用的提交类型和示例，你可以保存下来贴在团队文档里：
| 提交类型（type） | 说明 | 适用场景 | 示例 |
|---|---|---|---|
| feat | 新功能 | 新增页面、组件、API | feat(home): add banner carousel component |
| fix | 修复bug | 功能异常、兼容性问题 | fix(login): resolve password input timeout on iOS |
| docs | 文档更新 | README、注释、API文档 | docs: update installation guide for Vue 3 |
| refactor | 代码重构 | 不增功能、不改bug的代码优化 | refactor: simplify form validation logic |
接下来要让团队提交时必须遵守这个格式，这就需要commitlint和husky配合。先在项目根目录创建commitlint.config.js文件，内容如下：
module.exports = {
extends: ['@commitlint/config-conventional']
};
这个配置会让commitlint自动检查提交信息是否符合Angular规范。然后配置husky，在package.json里添加脚本：
{
"scripts": {
"prepare": "husky install"
}
}
运行npm run prepare初始化husky，再执行npx husky add .husky/commit-msg 'npx no -
，这样每次提交代码时，如果信息格式不对（比如只写“改了点东西”），Git就会直接拦截并提示错误，确保所有人都按规范提交。
第三步：配置自动生成脚本（一条命令出日志）
最后一步是让工具自动生成CHANGELOG.md。打开package.json，在scripts里添加：
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
}
}
这里解释下参数：-p angular指定用Angular规范解析commit，-i CHANGELOG.md表示更新现有文件（而不是生成新文件），-s是“same file”的缩写，-r 0表示生成所有版本的日志（首次使用时用，后续发版 改成-r 1，只生成最新版本）。
现在你可以测试一下：先提交一个符合规范的commit，比如git commit -m "feat(dashboard): add real-time data chart"，然后运行npm run changelog，打开生成的CHANGELOG.md，会看到类似这样的内容：
## [Unreleased]
Features
* dashboard: add real-time data chart (a1b2c3d)
如果你的项目已经有多个版本标签（比如v1.0.0、v1.1.0），工具还会自动按版本号分组，每个版本下区分“Features”“Bug Fixes”等板块，比手动写的整齐10倍。为了更方便，你还可以把日志生成和版本号更新结合起来，在package.json里再加个脚本：
{
"scripts": {
"version": "npm run changelog && git add CHANGELOG.md"
}
}
这样运行npm version patch（更新补丁版本）时，npm会自动更新package.json的version字段，然后运行changelog脚本生成日志，最后把更新后的CHANGELOG.md添加到Git暂存区，一步到位完成版本和日志的同步。
现在你已经掌握了conventional-changelog的核心配置方法，从安装依赖到生成日志，整个流程虽然要敲几行命令，但配好后基本一劳永逸。我自己带的团队用这套方案快两年了，现在发版时再也没人抱怨“整理日志比写代码还累”，甚至有新人说“看CHANGELOG.md比看文档还清楚每个版本改了啥”。你项目里现在是怎么管理变更日志的？如果还在手动复制粘贴commit记录，今晚下班前花20分钟试试这套配置，遇到依赖报错或日志格式不对的问题，都可以在评论区告诉我，咱们一起看看怎么解决！
你知道吗？GitHub和GitLab的Release功能跟conventional-changelog同步其实特别方便，我之前带的团队就是这么配的，现在发版连平台上的Release描述都不用手动写了。就拿GitHub来说，你只需要在项目里建个.github/workflows/release.yml文件，配置一下触发条件——比如当你推送版本标签（像v1.3.0这种）的时候，就让Actions自动跑起来。里面可以加两个步骤：先用actions/checkout拉取代码，再用actions/setup-node装好环境，然后运行npm run changelog生成最新日志。最关键的是调用GitHub官方的actions/create-release Action，把CHANGELOG.md里对应版本的内容抠出来当Release描述——比如你刚发了v1.3.0，就用grep -A 100 "## [1.3.0]" CHANGELOG.md | grep -B 100 "## [" | head -n -1这样的命令截取出这段日志，直接塞到body参数里，连commit链接都会自动带上。
GitLab的话稍微不一样，但思路差不多。你可以在.gitlab-ci.yml里加个release阶段，用GitLab自带的release-cli工具。先在variables里定义好RELEASE_VERSION（就是你package.json里的版本号），然后在script里写几行命令：先用npm run changelog更新日志，再用sed -n "/## [$RELEASE_VERSION]/,/## [/p" CHANGELOG.md | head -n -1把这个版本的日志内容提取出来，最后通过release-cli create name "Release $RELEASE_VERSION" description "$(cat release-notes.txt)"推到GitLab Release里。我之前还试过把构建好的dist包也一起上传，在jobs里加个artifacts，再用actions/upload-release-asset（GitHub）或者release-cli的assets参数（GitLab），用户下载安装包的时候就能直接看到对应版本的更新说明，比以前手动复制粘贴方便太多了。
已经有很多不规范的提交记录，还能生成正确的变更日志吗？
如果项目历史提交记录不符合规范（比如随意写“改了点东西”“修复bug”），直接使用conventional-changelog可能会导致日志内容混乱或缺失关键信息。这种情况下，可以先使用工具手动筛选和标记早期重要提交（如通过git rebase -i修改历史提交信息，适合提交记录较少的情况），或在首次配置时添加-r 0参数生成所有版本日志后，手动编辑早期版本内容。对于新提交，严格按规范执行即可，后续日志会自动保持整洁。
除了Angular规范，还能使用其他提交规范吗？
可以。conventional-changelog支持多种预设规范，除了文章中提到的Angular，还有Conventional Commits（通用规范）、ESLint、jQuery等。 若想使用更简洁的Conventional Commits规范，只需将生成命令中的-p angular改为-p conventionalcommits；如果项目是React生态，可尝试-p react预设。具体支持的预设列表可参考conventional-changelog官方文档。
生成的CHANGELOG.md能自定义格式吗？比如添加项目特定的分类？
可以自定义。默认生成的日志按“Features”“Bug Fixes”等分类，若项目需要添加特定板块（如“Performance Improvements”“Security Updates”），可通过创建自定义模板文件实现。 在项目根目录新建.changelogrc.js配置文件，指定分类规则和输出格式；或使用conventional-changelog-custom-config等插件，灵活定义标题、排序方式甚至链接格式。对于简单调整（如修改分类名称），也可直接编辑生成后的CHANGELOG.md，后续通过-s参数更新时，工具会保留手动修改的内容。
能和GitLab或GitHub的Release功能自动同步吗？
可以通过CI/CD工具实现自动同步。以GitHub为例，可配置GitHub Actions：当运行npm version更新版本并生成日志后，通过Actions调用GitHub API，自动创建Release并将CHANGELOG.md中对应版本的内容作为Release描述。具体步骤包括：在项目中添加.github/workflows/release.yml文件，配置触发条件（如推送版本标签），并使用actions/create-release等官方Action完成同步。这样团队成员无需手动在GitHub后台编辑Release，日志内容会自动同步到平台上。
