Composer依赖锁文件的版本控制技巧

必须提交 composer.lock 到 Git，它是依赖快照的唯一权威记录

一个核心原则必须明确：composer.lock 文件必须提交到 Git 仓库。否则，所谓的“依赖锁定”就形同虚设——它不是一个可选的缓存文件，而是整个项目依赖关系确切状态的唯一权威快照。

composer.lock 为什么必须进 Git

如果不提交 composer.lock，那么 composer install 这个命令就会“退化”成仅仅依据 composer.json 来重新解析依赖。这会导致什么后果呢？即使你在 composer.json 里白纸黑字地写着 "monolog/monolog": "2.9.1"，只要 lock 文件缺失，那么在 CI 环境或者新同事的电脑上安装出来的，就可能是 2.9.2 版本。听起来有点匪夷所思？其实触发这种重解析的因素很多：镜像源缓存了更新的版本、PHP 版本有细微差异、甚至系统扩展的状态不同，都可能让 Composer 做出不一样的选择。

• 最常见的误操作，就是在 .gitignore 文件里误写了 composer.lock 或者通配符 *lock*。
• 对于新项目，初始化后第一次运行完 composer install，就应该立刻执行 git add composer.lock。
• 在多人协作中，如果同事 A 提交了更新后的 lock 文件，而同事 B 修改了 composer.json 后直接运行 composer install，很可能会遇到 Your requirements could not be resolved to an installable set of packages 这样的错误。正确的做法不是删除 lock 文件重装，而是应该运行 composer update 来协调依赖并生成新的 lock 文件提交。

怎么验证 lock 文件是否真正生效

lock 文件生效的关键，在于 composer install 命令是否真的读取并严格执行了它，而不仅仅是文件存在。

• 这里有个简单的验证方法：删除 vendor/ 目录和 composer.lock 文件，只保留 composer.json，然后再次运行 composer install。如果安装过程没有报错，但装出来的包版本和之前不一致，那就说明 lock 文件没有起作用。这通常是因为文件被 .gitignore 忽略了，或者 CI 脚本错误地使用了 composer update。
• 因此，在 CI/CD 脚本中，必须使用 composer install --no-dev --no-interaction，坚决避免使用 composer update。
• 上线前还可以加一道保险：运行 composer install --locked。这个命令会校验 composer.lock 中记录的每个版本是否仍然满足 composer.json 里的版本约束，如果不满足则会直接报错退出，这能有效阻止不兼容的依赖变更被部署。

不同 PHP 版本导致 lock 失效怎么办

composer.lock 文件默认会包含平台配置信息（比如 php 版本、ext-zip 这类扩展）。如果团队中有人用 PHP 8.1，有人用 8.2，而某个依赖包在这两个环境下解析出来的依赖树路径不同，那么 lock 文件就可能失效。

• 检查 lock 文件顶部的 platform 字段。一个建议是，在 composer.json 的 config 部分显式声明团队统一使用的最低 PHP 版本，例如："config": {"platform": {"php": "8.1.0"}}。
• 尽量避免在 composer.json 中书写过于宽松的 PHP 版本约束，比如 "^7.4 || ^8.0"。这种写法会让 Composer 在不同环境下选择不同的依赖分支，使得 lock 文件失去跨环境一致性的意义。
• 另外，Windows 和 Linux 系统下某些扩展（例如 ext-sockets）的默认状态可能不同。如果项目依赖这类扩展，也应在 config.platform 中进行统一模拟声明，否则可能出现 lock 文件在 CI（Linux）上验证通过，在本地（Windows）却安装失败的情况。

手动改 lock 文件行不行

答案是：绝对不行。composer.lock 不是用来手动编辑的配置文件，它是一个由 Composer 自动生成的、记录所有包确切版本、哈希值和完整依赖路径的快照文件。手动修改极易引入错误。

• 举个例子，如果你只修改了某个包的 version 字段，却没有同步更新对应的 dist/sha256 哈希值，那么下次运行 composer install 时，校验就会失败并抛出 Invalid checksum for ... 的错误。
• 所有依赖变更的正确操作入口都是 composer.json。修改它，然后让 Composer 来重新生成 lock 文件。如果想锁定某个包，就在 composer.json 里写死版本号，例如 "monolog/monolog": "2.9.1"；如果想仅根据当前 composer.json 重新生成 lock 文件而不更新 vendor，可以运行 composer update --lock。
• 需要回退到之前的依赖状态？很简单，直接使用 Git 回滚 lock 文件即可：git checkout composer.lock && composer install。

说到底，最难的部分往往不是记住这些命令，而是让团队中的每个人都理解：composer.lock 不是构建过程的“生成物”或“副产品”，它是与 composer.json 同等重要的源代码文件。删除它、在版本控制中忽略它、或者在流程中绕过它，就等于主动放弃了依赖管理的版本控制，将项目置于潜在的不一致风险之中。