为什么composer.lock必须提交到Git？Composer协作开发的黄金法则

为什么composer.lock必须提交到Git？Composer协作开发的黄金法则

composer.lock 不提交 = 环境一致性失效

不提交 composer.lock，composer install 就会退化为 composer update 行为——它不再按“快照”安装，而是实时解析最新兼容版本。这意味着：同一份 composer.json，在你本地、CI 流水线、生产服务器上，可能装出完全不同的依赖组合。

常见错误现象包括：

• Class not found 或 Method does not exist —— 某个子依赖（如 psr/http-message）悄悄从 v1 升到 v2，破坏了向后兼容性
• CI 构建通过，但线上 500 白屏 —— monolog/monolog v2.9.1 和 v2.10.0 的日志处理器行为有细微差异
• 队友 git pull 后运行 composer install，vendor/ 里多出十几个文件、少掉几个类 —— 因为 lock 文件缺失，每人各自解析了一次

应用型项目 vs 库项目：提交规则完全不同

composer.lock 是否提交，取决于项目性质，不是凭感觉决定的。

必须提交的场景（应用型项目）：

• Lara vel 网站、Symfony API、WordPress 插件后台服务等可独立部署的项目
• 任何需要保证“开发 → 测试 → 生产”三环境依赖完全一致的系统

不应提交的场景（库/组件项目）：

• 发布为 Packagist 包的 PHP 库（如 myvendor/my-utils）
• 目的是被其他项目 require 的代码，需保持依赖灵活性，由下游项目控制锁文件

混淆这两类角色，是团队误删 composer.lock 的常见源头。

为什么 .gitignore 里出现 composer.lock 就等于埋雷

最常被忽略的问题不是“要不要提交”，而是“它是否真进了 Git”。很多人以为自己提交了，其实早被 .gitignore 拦下了。

验证方式很简单：

• 运行 git check-ignore -v composer.lock —— 如果有输出，说明它被忽略了，立刻删掉 .gitignore 中对应行
• 检查是否误写了 /composer.lock、composer.lock 或带空格的变体（如 composer.lock）
• 多人协作时，如果 A 提交了 lock，B 拉取后又执行了 composer install 却没 commit 新 lock，C 下次拉取就会拿到“过期 lock”

PHP 版本不一致也会让 lock 失效：lock 文件里记录了 platform 字段，若本地 PHP 是 8.2，而 CI 是 8.1，composer install 可能报 warning 甚至跳过某些包 —— 建议在 composer.json 中显式声明 "config": { "platform": { "php": "8.1.0" } }。

更新依赖时，lock 文件怎么动才安全

只要 composer.lock 在 Git 里，每次 composer install 就是确定性的；一旦脱离版本控制，“环境一致”就只剩玄学。

安全更新的实操要点：

• 想更新全部依赖？先跑 composer update --dry-run，看实际会动哪些包，尤其注意 sub-dependency 的 major 升级
• 只更新某一个包？用 composer update vendor/package --with-dependencies，但要清楚它仍会递归更新其子依赖
• 修复安全漏洞？优先用 composer update vendor/package --with-dependencies，而不是手动删 lock 后重生成
• 调试冲突？可临时加 --ignore-platform-reqs，但仅限本地，切勿提交修改后的 lock

真正麻烦的从来不是“要不要提交”，而是“谁改了 lock、为什么改、有没有同步通知”。只要它在 Git 里，每次变更都有迹可循；一旦绕过它，协作就回到了靠口头对齐版本的原始阶段。