composer update --lock 不解析依赖、不修改 vendor,仅根据当前 composer.json 和已安装包重写 composer.lock;适用于 lock 缺失但 vendor 完整的协作场景。

composer update --lock 会跳过依赖解析,只重写 lock 文件
这个参数的作用非常具体:它不下载、不解压、不修改 vendor/,只根据当前 composer.json 和已安装的包状态,重新生成一份与之精确匹配的 composer.lock。前提是所有包都已安装且版本满足约束——否则会报错并中止。
常见错误现象:Your requirements could not be resolved,但你确认没改 composer.json —— 很可能是因为某个包被手动删了、或 vendor/ 里有残留旧文件干扰了版本探测。
- 只适用于「
vendor/已存在且完整」的场景,比如你刚从 Git 拉了新代码,但同事忘了提交composer.lock,而你本地vendor/是全的 - 不会触发任何远程请求,也不读取缓存中的 metadata,所以比
composer update快得多 - 不校验平台要求(PHP 版本、扩展),所以即使当前环境不满足
composer.json的config.platform,它也可能成功生成 lock 文件 - 生成的 lock 文件中
packages列表和packages-dev会严格对应vendor/实际内容,而不是composer.json的声明顺序
什么时候该用 --lock,而不是直接 install 或 update
典型场景是协作开发中 lock 文件缺失或损坏,但你不想重装整个 vendor/(比如 CI 缓存了 vendor 目录,只缺 lock);或者你想快速验证当前 vendor/ 是否真的能被 composer.json 描述清楚。
- CI 脚本里:先
composer install --no-scripts(跳过 autoload 生成等耗时操作),再composer update --lock补 lock,最后composer dump-autoload -o - 你手动改过
vendor/里的某文件做调试,又想“还原” lock 文件记录的状态(注意:它不会还原文件,只记录当前状态) - 想检查是否有人偷偷在
vendor/里加了未声明的包 ——composer update --lock会把它们也写进 lock,后续composer install就会拉下来 - 不要用它替代
composer install:它不加载 autoload、不运行post-install-cmd、不创建 bin 符号链接
--lock 不解决缓存滞后或 ZIP 损坏问题
这个参数完全绕过网络和缓存逻辑,所以即使 ~/.composer/cache/repo/ 里的 metadata 过期了,或者某个包的 ZIP 在 cache/files/ 下已损坏,它也不会感知、更不会修复。
- 如果你执行
composer update --lock后,紧接着composer install报Corrupted zip file,说明问题出在缓存 ZIP,不是 lock 文件 - 它不会清理或刷新
composer.lock中的dist.sha256字段,所以如果远程包已更新但哈希变了,这个 lock 文件依然指向旧 ZIP - 若你刚升级了 PHP 版本,某些包的
platform约束已不满足,--lock仍会成功,但后续install会失败
替代方案:比 --lock 更安全的 lock 重建方式
真正想“从当前 vendor 状态生成可信 lock”,推荐组合命令,而非单靠 --lock:
- 先跑
composer validate确保composer.json语法和约束合法 - 用
composer show --installed确认vendor/里所有包都符合composer.json的 require 声明(尤其注意 dev 包是否多余) - 执行
composer update --lock --dry-run预检,看是否有冲突或缺失包 - 确认无误后,再执行
composer update --lock - 最后
git add composer.lock并提交 —— 因为这份 lock 只反映你本地 vendor 状态,不具备跨环境可复现性,必须人工确认
最易被忽略的一点:--lock 生成的 lock 文件,其 content-hash 是基于当前 composer.json 内容算的,但 packages 列表却来自 vendor/ 实际结构。这意味着,如果 vendor/ 里混入了未声明的包,这个 hash 就失去了校验意义。











