Class not found 或 require() 失败八成因 composer.lock 未同步:它是依赖“快照凭证”,缺失则 install 失去依据,环境一致性崩盘;install 严格按 lock 安装,update 则重解析版本,CI/CD 误用 update 易引入未验证不兼容变更。

本地跑得好,线上报 Class not found 或 require(): failed to open stream?八成不是代码问题,是 composer.lock 没同步到位。它不是可选文件,而是你整个 PHP 依赖的“快照凭证”——丢了它,composer install 就失去依据,环境一致性直接崩盘。
为什么 composer install 不等于 composer update
composer install 会严格读取 composer.lock 中记录的每个包的精确版本、哈希值、嵌套依赖树,然后原样安装;composer update 则完全忽略 composer.lock,只看 composer.json 的约束,重新解析并拉取最新兼容版本——这会导致线上装的包和你本地测试过的根本不是同一组。
- CI/CD 流水线里一旦误用
composer update,可能引入未验证的补丁版甚至小版本升级,触发静默不兼容(比如某次monolog/monolog的 v2.13.0 修复了日志格式但破坏了你自定义的处理器) - 团队中有人改了
composer.json却没提交新composer.lock,此时composer install会直接失败并报错:Root composer.json requires xxx, but it is not satisfied—— 这不是 bug,是 Composer 在拦你上线“残缺配置” -
composer.lock不存在时,composer install会自动退化为composer update行为,等同于放弃版本锁定
composer.lock 冲突了到底该删还是该合并
Git 合并时出现 composer.lock 冲突,别打开它手动改。这个文件不是配置,是生成结果,手动编辑等于绕过 Composer 的依赖求解器,大概率产出非法 JSON 或逻辑矛盾的锁文件。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
- 先确认
composer.json是否已无冲突:如果composer.json本身有分歧,必须先理清依赖增删逻辑,再操作 lock - 若只是两个分支各自加了不同 dev 包(比如 A 分支加了
phpunit/phpunit,B 分支加了laravel/pint),最稳做法是:删除本地composer.lock和vendor/,运行composer install让它按当前composer.json重建 - 若涉及关键运行时依赖升级(如
laravel/framework从 v10 升到 v11),不能简单覆盖 lock,应先在干净环境执行composer update laravel/framework --with-all-dependencies,再提交新 lock - 避免使用已废弃的
composer-merge-plugin:它试图“合并” lock 文件,但官方明确不支持多源 lock 合并,且插件本身早已停止维护
部署时常见失败原因和对应检查项
composer install 在线上失败,往往不是网络或权限问题,而是 lock 文件和当前环境存在隐性不匹配。
- 检查 PHP 版本是否满足
composer.lock中的"platform": {"php": "^8.1"}约束:线上是 PHP 8.0?那必然失败,不能靠--ignore-platform-reqs硬上,这会跳过所有扩展和版本校验,埋下 runtime 崩溃隐患 - 确认
composer.json和composer.lock是配套的:改过composer.json后没跑composer update,lock 就是过期的,install 会拒绝执行 - Windows 下若报
file could not be downloaded: failed to open stream: HTTP request failed!,大概率是 OpenSSL 的 ca-bundle 路径失效,临时可用--no-secure-http(仅限开发机),生产环境必须修复证书配置 - CI 构建失败却提示
Package operations: 0 installs, 0 updates, 0 removals?说明 lock 文件里记录的包在当前源(如 packagist.org)已不可用(被删、重命名或私有化),需检查源配置或联系包维护者
真正容易被忽略的点是:lock 文件只保证“当时能装”,不保证“永远可用”。Packagist 下架、私有包权限变更、PHP 版本淘汰,都会让一个曾经完美的 lock 文件突然失效。所以定期运行 composer outdated 并结合 composer update --dry-run 做轻量评估,比等到线上炸了再救火要实在得多。

















