composer如何自动生成CHANGELOG？（结合conventional commits）

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。