conventional-changelog 工具依赖规范提交前缀（如 feat:、fix:）才能正确识别类型并生成 CHANGELOG；若提交不规范或未打语义化 tag，则输出为空或仅含 “Other” 条目，需配合 commitlint + husky 校验、正确配置 composer scripts 并在发版前打 tag。
conventional-commits 为什么必须先规范提交格式
不按 feat:、fix:、chore: 等前缀写提交，conventional-changelog 工具根本识别不出类型，生成的 CHANGELOG 就是空的或全是 other 条目。
常见错误现象：conventional-changelog -p angular -i CHANGELOG.md -s 运行后 CHANGELOG.md 没变化，或者只有一行 “### Other”；实际是 Git 历史里混着 git commit -m "update readme" 这类非规范提交。
- 团队必须统一执行
npm install -D @commitlint/{config-conventional,cli}+ 配合husky提交前校验 -
conventional-changelog默认只读取最近一次 tag 到 HEAD 的提交，如果没打过 tag，它会尝试从项目初始提交开始扫——但遇到非规范提交就停，不是跳过 - Angular preset（
-p angular）要求fix:和feat:必须带括号作用域，比如fix(auth): token expiry check，缺括号也会被降级为other
composer.json 里怎么配才能让 changelog 自动生成
Composer 本身不生成 CHANGELOG，真正干活的是 Node.js 工具链。但你可以用 composer run 把它“包”进去，让 PHP 团队也能无感调用。
在 composer.json 的 scripts 区域加一条：
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s --commit-path ."
注意几个关键参数：
-
-p angular：用 Angular 规范解析提交（最常用，兼容性好） -
-i CHANGELOG.md：指定输入/输出文件，必须存在（首次运行前touch CHANGELOG.md） -
-s：直接写入文件，不打印到终端 -
--commit-path .：显式告诉工具从当前目录找 Git 仓库（否则在子目录执行时可能失败）
之后运行 composer run changelog 就等价于跑 Node 命令——前提是项目根目录已安装 conventional-changelog-cli（推荐全局装或 devDependencies 里装）。
生成的 CHANGELOG 版本标题怎么对应 Git tag
默认情况下，conventional-changelog 会把最新一次 tag 当作 “Unreleased” 上方的正式版本标题，比如你刚打了 v1.2.0，它就会在 CHANGELOG 顶部补上 ## [1.2.0](https://...)，然后把 v1.2.0 到 HEAD 的提交归到 ## [Unreleased] 下。
容易踩的坑：
- 没打 tag 就跑命令 →
[Unreleased]下永远空，因为工具找不到上一个锚点 - tag 名不是语义化格式（如
release-2024或1.2缺少补零）→ 工具无法解析版本号，整个分组逻辑失效 - 想跳过
[Unreleased]直接生成已发布版本？不行。它必须有这个区块作为占位，否则后续增量更新会错乱
正确做法：每次发版前先 git tag v1.2.0，再 composer run changelog，最后 git add CHANGELOG.md && git commit -m "chore(release): update CHANGELOG for v1.2.0"。
PHP 项目里要不要把 Node 工具塞进 vendor
不要。Node 工具和 PHP 生态无关，硬塞进 vendor 会破坏 Composer 的职责边界，还会让 composer install 变慢、CI 构建更难维护。
可行方案只有两个：
- CI 流水线里单独
npm ci安装conventional-changelog-cli，再跑composer run changelog - 本地开发用
nvm管理 Node 版本，全局安装npm install -g conventional-changelog-cli，确保所有成员环境一致
关键是别让 PHP 同事去学 npm lockfile 或 node_modules 权限问题——他们只需要知道：改完提交、打好 tag、composer run changelog，三步做完就能推 PR。
