composer.lock 与 composer.json 不同步时应通过 composer validate、--dry-run 或 status 检查，并依场景执行 update --lock、install 或 Git 恢复；预防需规范流程与提交习惯。
当 composer.lock 与 composer.json 不同步，通常意味着依赖声明已变但锁文件没更新，或锁文件被手动修改、误删、版本回退等。这会导致安装行为不一致、CI 失败、本地与生产环境差异等问题。核心原则是：lock 文件应始终反映 json 中声明的约束在当前解析下的确定结果。
如何判断是否真的不同步？
Composer 自带检查机制，运行以下命令即可验证：
-
composer validate—— 检查 json 格式及基本合规性（如 license 字段是否合法） -
composer install --dry-run—— 不实际安装，仅模拟并报出“需更新 lock”或“lock 过期”提示 -
composer status—— 显示哪些 vendor 下的文件被本地修改（间接反映 lock 可能失效） - 更直接的方式：
composer show --outdated看是否有包版本可升但未体现在 lock 中（说明 lock 锁定了旧版本，而 json 允许新版本）
常见不同步场景与对应操作
场景一：改了 composer.json（如加/删/调版本），但忘了运行 update
- 执行
composer update --lock（推荐）—— 仅更新 lock 文件，不重装包，快速对齐约束 - 或执行
composer update nothing（等价于composer update --lock），语义更清晰
场景二：lock 文件被意外删除或清空
- 直接运行
composer install—— Composer 会根据 json 重新生成 lock 并安装依赖（前提是 json 合法且网络可达） - 若想严格复现旧环境（比如你记得上次 commit 的 lock 是可靠的），应从 Git 恢复：
git checkout HEAD -- composer.lock
场景三：多人协作中 lock 被合并冲突破坏
- 不要手动编辑 lock 文件修复冲突 —— 它是自动生成的 JSON，结构复杂易错
- 先用
git checkout --ours composer.lock或--theirs保留一方，再立刻运行composer update --lock重建 - 更稳妥做法：双方先
git pull，再统一执行composer update --lock，提交新 lock
预防不同步的实用习惯
不同步本质是流程断点，靠工具+习惯堵住漏洞：
- 把
composer install当作“部署命令”，只在有合法 lock 时运行；CI/CD 中禁止使用update，强制install - Git 提交前加钩子（如 pre-commit）自动运行
composer validate && composer update --lock --dry-run，失败则中断提交 - 团队约定：所有
composer.json变更后，必须附带更新后的composer.lock提交（Git diff 应同时看到两者变化） - 避免直接修改
vendor/下代码 —— 如需定制，用 patch 或 fork + repositories 方式，否则install会覆盖，导致 lock “看似有效实则失效”
基本上就这些。不同步不是故障，而是信号：提醒你依赖关系的确定性正在松动。守住 lock 文件的权威性，比追求“最新版”更能保障项目稳定。
