PHP项目变更日志自动提取提交记录生成全指南
目录导读
- 为什么需要自动生成变更日志？
- Git提交规范是自动化的基石
- 主流自动提取工具对比与选型
- 实战：使用conventional-changelog集成PHP项目
- 高级定制：按版本与模块自动分类
- CI/CD流水线中嵌入自动生成
- 常见问题与避坑指南（FAQ）
为什么需要自动生成变更日志？
在PHP项目开发中，每次版本迭代都可能涉及数十甚至上百次Git提交，手动记录“新增功能”“修复Bug”“性能优化”等变更，不仅耗时且极易遗漏，更重要的是，传统手动维护的CHANGELOG.md往往存在以下痛点：
- 信息碎片化：开发者提交时随意写“fix bug”“update”，导致日志无法追溯具体改动
- 版本对齐困难：无法自动按照tag版本号生成结构化的“新增/修复/变更”分类
- 协作低效：团队成员需要频繁口头沟通“这个版本改了什么”
- 审计缺失：生产环境出现问题后，无法快速定位是哪个提交引入了问题
自动提取方案的核心价值在于：只要团队遵循统一的提交规范（如Conventional Commits），就可以通过脚本或CI工具，将每次git log中的结构化信息自动解析、分类、去重，最终生成格式统一、版本清晰的CHANGELOG文件，这不仅节省人工时间,还能确保文档与代码变更始终保持同步。
Git提交规范是自动化的基石
无论是使用哪种工具，自动提取的前提都是提交信息结构化，目前业界通用的标准是约定式提交,其基本格式如下：
<type>(<scope>): <subject>
<body>
<footer>常见的type类型（直接关系到后续日志分类）：
feat：新功能（对应CHANGELOG中的Features）fix：Bug修复（对应CHANGELOG中的Bug Fixes）docs：文档变更style：代码格式调整（不影响逻辑）refactor：代码重构（既非新增也非修复）perf：性能优化test：测试相关chore：构建过程或辅助工具变动
示例：
feat(用户模块): 增加邮箱验证功能
实现了用户注册后邮箱验证的逻辑，支持SMTP发信。
Closes #235如果团队尚未采用该规范，建议通过Git hook（如commit-msg钩子）强制校验提交格式，可使用工具如commitlint来约束。
主流自动提取工具对比与选型
针对PHP项目,目前社区常用的自动生成工具主要有以下几类：
| 工具名称 | 语言/依赖 | 核心特点 | 适合场景 |
|---|---|---|---|
| conventional-changelog-cli | Node.js | 支持Conventional Commits，可自定义配置，生成markdown | 通用场景，PHP项目也可集成 |
| semantic-release | Node.js | 全自动版本管理和发布，包含changelog | CI/CD一体化 |
| auto-changelog | Node.js | 轻量级，仅生成日志 | 小型项目快速起步 |
| github-changelog-generator | Ruby | 集成GitHub Issues/PR | 托管于GitHub的项目 |
| git log + 自定义脚本 | PHP (shell_exec) | 完全自主可控 | 追求极致定制 |
推荐方案：对于PHP项目，优先推荐conventional-changelog-cli，虽然它是Node.js写成的，但通过npm全局安装，可以在任何PHP项目的Git根目录下直接运行,它支持：
- 根据Git tag自动划分版本段
- 自动识别
feat、fix、breaking changes等类别 - 输出格式可自定义
- 可配合
standard-version实现版本号升级+日志生成一步到位
实战：使用conventional-changelog集成PHP项目
安装必要工具
如果你的开发环境已安装Node.js,直接全局安装：
npm install -g conventional-changelog-cli
创建基础配置文件
在项目根目录创建package.json（即使项目本身是PHP，也可以添加这个用于配置）：
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
}
}
参数说明：
-p angular：采用Angular推荐的提交规范-i CHANGELOG.md：输出文件-s：增量写入（追加新版本内容）-r 0：从第一个版本开始生成，-r 1表示从最新版本生成
首次生成
确保项目已经有Git tag（例如v1.0.0），如果没有,先打一个tag：
git tag v1.0.0 git push --tags
然后运行：
npm run changelog
你会看到CHANGELOG.md生成如下结构：
# Changelog ## [1.0.0] - 2025-06-15 ### Features - 用户模块：增加邮箱验证功能 - 支付模块：支持微信支付回调 ### Bug Fixes - 修复登录页面CSRF token失效问题 - 修复PHP8.2中弃用函数的兼容性
版本更新时的自动化生成
当发布新版本时，使用standard-version可以自动打tag并更新CHANGELOG：
npm install -g standard-version # 执行后会自动分析提交，升级版本号，生成日志，打tag standard-version
高级定制：按版本与模块自动分类
1 自定义分类映射
默认工具将type直接映射为英文标签（Features/Bug Fixes），如果希望输出中文或自定义名称，可以在package.json增加配置：
{
"conventional-changelog": {
"preset": "angular",
"releaseCommitMessageFormat": "chore(release): {{currentTag}}",
"writerOpts": {
"transform": {
"feat": "✨ 新功能",
"fix": "🐛 修复",
"perf": "⚡ 性能优化",
"refactor": "♻️ 重构",
"docs": "📝 文档"
}
}
}
}
2 排除非业务提交
如果提交中包含大量chore或style类型,可以在脚本中过滤：
conventional-changelog -p angular -i CHANGELOG.md -s -r 1 --skip-unstable
3 与PHP代码结合
由于项目本身是PHP，也可以编写一个PHP脚本来执行生成命令,适合在Laravel或Symfony的artisan命令中使用：
<?php
// app/Console/Commands/GenerateChangelog.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Symfony\Component\Process\Process;
class GenerateChangelog extends Command
{
protected $signature = 'changelog:generate';
protected $description = '自动从Git提交生成变更日志';
public function handle()
{
$process = new Process(['npx', 'conventional-changelog', '-p', 'angular', '-i', 'CHANGELOG.md', '-s', '-r', '1']);
$process->setWorkingDirectory(base_path());
$process->run();
if ($process->isSuccessful()) {
$this->info('变更日志已更新！');
} else {
$this->error($process->getErrorOutput());
}
}
}
CI/CD流水线中嵌入自动生成
为了确保每次合并到主分支或发布时自动更新CHANGELOG，可以将其整合到CI流程（以GitLab CI为例）：
# .gitlab-ci.yml
stages:
- changelog
- release
generate-changelog:
stage: changelog
only:
- main
before_script:
- npm install -g conventional-changelog-cli
script:
- git checkout main
- conventional-changelog -p angular -i CHANGELOG.md -s -r 1
- git config user.email "ci@example.com"
- git config user.name "CI Bot"
- git add CHANGELOG.md
- git commit -m "docs(changelog): update CHANGELOG.md"
- git push origin main
注意：需要为CI配置访问仓库的SSH密钥或Personal Access Token。
常见问题与避坑指南（FAQ）
Q1：我确保提交都是feat/fix格式，但工具却没有正确分类？
A：检查提交信息中是否包含BREAKING CHANGE标记，如果提交中有这个标记，它会自动归入“BREAKING CHANGES”类别，请确认提交的标题行严格遵循type(scope): subject格式,不要有空格或标点异常。
Q2：生成的CHANGELOG.md包含了所有历史提交，内容太长怎么办？
A：在生成时加上-r 1参数（只处理最新的一个版本），或者使用--output-unreleased只输出未发布的内容，对于已有大量历史记录，建议从头开始规范提交,然后只保留最新几个版本的日志。
Q3：PHP项目中没有Node.js环境怎么办？
A：有两种方案：1）在CI/CD环境中预装Node.js；2）使用纯PHP的替代工具，如php-changelog-generator（基于git log解析，但功能较弱），推荐第一种，因为conventional-changelog的生态更成熟。
Q4：如何确保每个版本只显示必要的提交，而不出现重复？
A：核心是正确打Git tag，工具会依据git tag来划分版本区间，如果两个tag之间没有提交，则不会生成新版本条目，建议每次发布前先合并代码，然后打一个语义化版本tag（如v2.1.0）。
Q5：自动生成的日志如何与Jira/禅道等项目管理工具关联？
A：可以在提交信息中使用JIRA-123或#issue引用，然后在CHANGELOG模板中通过自定义配置保留这些编号，后续可以在生成后手动增加链接前缀,或者在CI脚本中通过sed正则替换来实现超链接化。
通过上述方法，PHP项目团队可以彻底告别手动整理变更日志的繁琐工作，核心在于三个闭环：规范提交 → 自动化解析 → 持续集成，一旦跑通，每次版本发布，CHANGELOG将自动与代码变更保持精确同步,让项目可追溯性达到全新水平。
