composer update vendor/package 不可追溯，因它不生成变更日志、不校验PHP兼容性、不触发测试、不记录升级原因；必须修改composer.json显式声明版本与注释，并提交composer.lock，才能实现完整可追溯。
直接更新 composer.json 并执行 composer update 不等于构建可追溯流水线——它缺少版本锚点、变更记录和环境一致性保障。真正的可追溯，是指每次包升级都能回溯到「谁在何时因何原因升了哪个包、升到哪版、影响了哪些依赖、是否通过测试」。
为什么 composer update vendor/package 本身不可追溯
单独运行该命令不生成变更日志，不强制校验 PHP 版本兼容性，也不自动触发测试或缓存清理。更关键的是：它只改 composer.lock，但不会把这次修改的上下文（比如 PR 描述、安全公告链接、测试结果）一并存入 Git 历史。
-
composer update monolog/monolog后，git diff composer.lock只能看到哈希和版本号变化，看不出“这是为修复 CVE-2026-12345 而升的” - 如果没提交
composer.json中的版本约束（如把"^2.8"改成"^2.10"），下次composer install在 CI 中可能拉不到预期版本 - 未加
--dry-run直接执行，可能连带升级psr/log到不兼容版，而composer.lock里已悄悄记录，本地却没跑测试
必须写进 composer.json 的三类信息
可追溯的前提是声明意图。只靠 composer.lock 不足以说明“为什么升这个包”，必须让 composer.json 承载决策依据：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 显式版本约束：把
"monolog/monolog": "^2.8"改成"monolog/monolog": "2.10.0"（精确版）或"^2.10"（明确放宽边界），而非留空用* - 平台声明：确保
"platform": {"php": "8.2.10"}与当前运行环境一致，否则composer update可能跳过某些兼容版本 - 注释区块（非 JSON 标准但被主流编辑器识别）：在
composer.json顶部或对应包下方加// CVE-2026-12345: upgrade required或// #PR-421: align with Laravel 10.42
composer update 前后必须做的四件事
跳过任意一步，都会让“可追溯”变成“可猜疑”：
- 运行
composer update vendor/package --dry-run，确认输出中没有意外的间接升级（尤其是symfony/*、psr/*类基础包） - 执行
composer why-not vendor/package:3.0（如果目标是主版本）——不是为了强行升级，而是看清楚阻塞链上哪个包卡住了 - 更新后立即运行
composer dump-autoload -o，否则新类可能加载失败；Laravel/Symfony 项目额外补php artisan config:clear和php artisan cache:clear -
git add composer.json composer.lock && git commit -m "chore(composer): upgrade monolog/monolog to 2.10.0 for CVE-2026-12345"—— 提交信息必须含包名、版本、原因
CI 流水线里不能只跑 composer install
很多团队在 GitHub Actions 或 GitLab CI 里只写 composer install --no-dev，这保证了安装一致性，但放弃了追溯入口。真正可审计的流水线要分两层：
- 开发分支 PR 阶段：触发
composer update vendor/package --with-dependencies+composer validate+composer test（需提前在composer.json中定义"scripts": {"test": "phpunit"}） - 主干合并后：用
composer install --no-dev --prefer-dist安装，但必须校验composer.lock是否由合法 PR 更新而来（例如检查 commit message 是否含chore(composer):） - 禁止在 CI 中使用
composer update无参数形式——它绕过了所有人工审查，且composer.lock变更无法关联到具体 issue 或人
最常被忽略的点：composer.lock 文件里的 content-hash 值会随 composer.json 的注释变化而改变。这意味着你加的一行 // fix security 也会导致 hash 变动——这不是 bug，是设计，它迫使你把所有上下文都放进 Git 提交，而不是藏在本地注释里。
