本文目录导读：
- 方法一：使用
CHANGELOG.md文件（推荐，通用性强） - 方法二：利用
composer.json的extra字段（面向 Composer 包） - 方法三：使用 Git Tag + 自动生成 Release Notes（适合 CI/CD）
- 方法四：在 PHP 代码中通过注解/属性记录（针对内部组件变更）
- 方法五：使用专门的变更管理工具（适合中大型团队）
- 推荐组合（最佳实践）
在PHP项目版本迭代中记录组件变更日志,通常有以下几种主流且实用的方法，根据项目规模、团队习惯和工具链，你可以选择最适合的一种或组合使用。
使用 CHANGELOG.md 文件（推荐，通用性强）
这是最通用、最推荐的做法，遵循 Keep a Changelog 规范，位于项目根目录。
核心结构：
# Changelog 所有对项目的重要变更都会记录在此文件中。 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， 并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 ## [1.2.0] - 2024-05-20 ### 新增 - 添加用户头像上传功能 (#123) - 新增 `UserExportService` 组件，支持 CSV 导出 ### 变更 - 将数据库驱动从 MySQL 切换为 MariaDB - 重构 `PaymentGateway` 组件，提升事务处理速度 ### 废弃 - 计划在 2.0 版本移除旧版 `SessionHandler` 类 ### 修复 - 修复 `UserController` 中分页参数未校验导致的 SQL 注入风险 (CVE-2024-XXXX) ### 安全 - 升级 `monolog/monolog` 到 v3.6.0 以修复低版本 RCE 漏洞 ## [1.1.0] - 2024-04-15 ### 新增 - 添加日志记录组件 `RequestLogger`...
适用于： 任何 PHP 项目（Laravel, Symfony, ThinkPHP, 原生等）。
优点： 标准化、易于阅读、GitHub/GitLab 会自动渲染、支持自动化生成工具。
提示：可以配合 git-cliff 或 standard-version 等工具，从 Git 提交历史自动生成此文件。
利用 composer.json 的 extra 字段（面向 Composer 包）
如果你开发的组件是一个 Composer 包（vendor/your-package），可以利用 extra 字段记录变更摘要，或直接在包内包含 CHANGELOG.md。
{
"name": "vendor/your-package",
"version": "1.5.2",
"extra": {
"changelog": {
"1.5.2": "修复数据库连接池泄漏问题",
"1.5.1": "增加对 PHP 8.3 的支持",
"1.5.0": "重构缓存组件，性能提升 30%"
}
}
}
但更推荐的做法： 在包根目录放置 CHANGELOG.md，同时确保 composer.json 中的 version 标签与 Git Tag 保持同步。
使用 Git Tag + 自动生成 Release Notes（适合 CI/CD）
工作流程：
-
规范提交信息：使用 Conventional Commits 规范。
feat(cache): 添加 Redis 集群支持 fix(db): 修复连接池泄漏问题 BREAKING CHANGE: 移除了对 PHP 7.4 的支持
-
打 Tag：
git tag v2.1.0 git push origin v2.1.0
-
自动生成 Release Notes：
- GitHub：在 Releases 页面点击“Generate release notes”。
- GitLab：使用内置的 Release 功能。
- 自建 Git：使用
git-cliff或semantic-release等工具，在 CI 中自动生成变更日志。
示例（GitHub CLI）：
gh release create v2.1.0 --generate-notes
适用于： 使用 GitHub/GitLab/Gitee 托管、有 CI/CD 流程的团队。
在 PHP 代码中通过注解/属性记录（针对内部组件变更）
适合大型框架或内部组件库,通过静态分析工具生成报告。
#[ComponentChange(
version: '2.1.0',
date: '2024-05-20',
description: '重构支付网关，统一错误码格式',
author: '张三'
)]
class PaymentGateway {
// ...
}
需要配合自定义的注解解析器或使用 phpstan/phpdoc-parser 生成文档。
优点： 变更信息离代码最近，方便开发者查看。 缺点： 依赖工具解析，社区不够成熟。
使用专门的变更管理工具（适合中大型团队）
- Jira / Notion / Confluence：将组件变更记录为子任务或技术卡片，与版本发布关联。
- Phabricator：使用 Herald 规则自动记录变更。
- 自定义内部工具：结合 Git 钩子 + API，将变更记录推送到内部知识库。
推荐组合（最佳实践）
| 场景 | 推荐方案 |
|---|---|
| 开源项目 / 公共组件 | CHANGELOG.md (Keep a Changelog) + GitHub/GitLab Releases |
| 企业内部包 | CHANGELOG.md + Git Tag + 自动生成 Release Notes |
| 极简团队（1-3人） | CHANGELOG.md 手动维护，只记录重要变更和破坏性更改 |
| 大型项目（10+人） | Conventional Commits + CI 自动化生成 + 内部 Wiki 记录详细决策背景 |
最低配置（建议任何项目都执行）：
- 项目根目录有一份
CHANGELOG.md。 - 每次发版时,按 新增 / 变更 / 修复 / 废弃 / 移除 / 安全 分类记录。
- 每个版本号对应一个 Git Tag。
- 如果涉及 Composer 组件，同时在
README.md或组件文档中简要说明。
这样无论团队如何扩展,或者项目被其他人接手，都能快速了解每个版本的变更意图和影响范围。
