Composer安装失败:核对PHP版本与扩展
适用范围:Composer 2项目的安装与部署。运行composer install时,提示PHP版本不满足要求,或缺少ext-mbstring、ext-zip等扩展,应先核对Composer真正使用的PHP环境。网站面板显示某个PHP版本,并不代表终端也在使用它。
一、先看错误属于哪一类
| 报错内容 | 优先检查 |
|---|---|
| requires php,后面列出版本条件 | 执行Composer的PHP版本是否满足该条件 |
| requires ext-xxx,提示missing | 对应PHP是否安装并实际加载该扩展 |
| 锁文件与composer.json不一致 | 是否混用了不同发布版本的文件 |
如果是连接超时、下载失败或证书错误,应按对应问题处理,不能用安装扩展来解决。先保存完整错误,尤其是具体依赖名称和要求的版本范围。
二、核对终端里的PHP与配置文件
在Linux终端执行:
command -v php
php -v
php --ini
command -v composer
composer --version
php --ini会列出当前命令行PHP读取的主配置与附加INI。扩展必须对实际执行Composer的解释器生效,不能只看面板上是否勾选。
多PHP环境下,Composer启动脚本可能使用另一个解释器。使用PHAR安装方式时,可以明确指定已有PHP和Composer文件的完整路径,例如:
/opt/php/bin/php /opt/tools/composer.phar --version
这只是路径写法示例,两个文件必须替换为实际存在的路径。后续检查与安装保持使用同一解释器;不要为一次安装随意替换全局PHP软链接。下文以composer命令已正确指向目标环境为例。
三、安装失败时,先按锁文件检查要求
进入包含composer.json的项目目录。已有composer.lock时执行:
composer validate
composer check-platform-reqs --lock
--lock从锁文件检查要求,适合依赖尚未装好的情况。查看输出中失败的具体项目:php失败就核对版本,ext-xxx失败就核对对应扩展。
此检查使用真实PHP环境,不会把config.platform中模拟的版本当成实际能力。修改那个版本数字,不会替你升级PHP或安装扩展。
四、只补齐当前PHP缺少的扩展
例如提示缺少ext-mbstring,执行:
php --ri mbstring
php -m
若显示扩展不存在,就通过当前PHP来源对应的管理工具或软件包安装、启用它,再重新检查。使用独立PHP路径时,上面的php也要换成同一路径。不要给一个PHP版本装扩展,却用另一个版本运行Composer。
扩展文件已存在但仍未加载,应检查php --ini列出的配置及启动警告。命令行PHP下一次启动会重新读取配置;网站PHP是否需要重载,应按其运行方式处理。
五、修好环境后,使用原锁文件安装
已有锁文件的项目,install使用其中锁定的依赖版本;update会重新解析依赖并更新锁文件。不要为了消除错误在生产目录盲目执行update,也不要先删锁文件。
如果锁文件缺失或与代码不匹配,先从同一发布版本补齐。首次部署确实没有锁文件时,应按项目文档在测试环境确认依赖方案,而不是把重新解析当成无变化重装。
安装会修改依赖目录,也可能执行项目脚本或插件。先确认项目来源可信,保存原发布文件,并在测试环境验证后按发布流程操作,不在运行中的业务目录反复试错。
composer install
composer check-platform-reqs
仅当部署方案明确排除开发依赖时,安装与检查同时使用--no-dev。不要用它隐藏项目真正需要的依赖,也不要添加--ignore-platform-reqs跳过环境检查。
六、命令通过后,还要检查网站
Composer检查的是执行它的环境。网站使用PHP-FPM或其他运行方式时,还需确认站点绑定的版本与扩展同样满足要求,再测试实际页面、接口和后台任务。终端成功不能代替网站验收。
需要协助时,提供完整报错、php -v、php --ini、平台检查结果和站点PHP版本。不要公开auth.json、仓库密码或访问令牌。
站点端的版本与扩展核对可参考宝塔网站切换PHP版本与安装扩展及PHP扩展安装与配置生效检查。