Composer故障排除：总结解决安装报错的50个常见方案

Composer报错这事儿，说白了就这几种底层原因——环境、配置、权限、网络，哪一个环节出问题都不奇怪。与其反复重装Composer，不如直接看错误关键词——后者比前者有效十倍。

“Your requirements could not be resolved”是依赖冲突，非网络或权限问题；本质是Composer无法找到满足所有约束的版本组合，常见于PHP版本/扩展不匹配、死版本号冲突或老旧包强制低版本依赖。

Composer的报错从来不是随机事件——是你的环境、配置、权限或网络中某个具体环节出了问题。直接瞄着错误关键词下手，比重装Composer有效十倍。

报错含“Your requirements could not be resolved”

这不是网络崩了，也不是权限拦路，而是依赖之间的约束互相打架。Composer算半天，发现没法儿同时满足你require的所有版本需求。

• 直接跑composer why-not php:8.3（把8.3换成你目标PHP版本），立马定位是哪个包在捣乱
• 常见的几个坑：Lara vel升级后没同步更新配套包；有人手贱锁死了某个包的版本（比如"monolog/monolog": "2.9.0"）；或者某个老掉牙的bundle（比如jms-security-extra-bundle）死咬着Symfony 2.x或PHP 5.6不放
• 别删composer.lock——它记录的是已经验证可行的版本组合。删了它，问题反而更难复现
• 临时绕过可以用composer install --ignore-platform-reqs，但只适合调试阶段。线上环境必须老老实实修兼容性，否则ext-pcntl、ext-redis缺了都不会报错，到时候跑起来才叫麻烦

卡在“Loading composer repositories”或提示“Connection timed out”

国内直连packagist.org基本看运气。本质上不是你家网络坏了，而是DNS、TLS握手或是中间链路被拦了一道。

• 换镜像源是最直接的解法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• 换完源一定清缓存：composer clear-cache
• 企业网络或者信号不好的环境，可以拉长超时时间：composer config -g process-timeout 3000和composer config -g http-timeout 600
• 有些防火墙会拦SNI请求，临时关掉TLS验证也能搞定：composer config -g secure-http false（这步只限开发机，生产环境千万别用）
• CI脚本里来回切源反而拖慢构建，全局配一次就够了

Permission denied: failed to create directory vendor/

典型的权限错乱，尤其多见于WSL、Docker或者误用sudo的后遗症。跟Composer本身无关——是你当前用户没有那个路径的写入权限。

• 绝对不能用sudo composer install——一旦用了，vendor/下所有文件属主都变成root，后续php artisan或者启动本地服务器时直接翻车
• WSL用户注意：如果项目放在/mnt/c/xxx下，NTFS不支持Linux权限模型，chmod根本没用。唯一稳解是移到WSL原生路径，比如~/projects/myapp
• 检查归属：ls -ld vendor ~/. composer/cache，如果属主是root，修复命令如下：sudo chown -R $USER:$USER vendor ~/. composer/cache
• 也可以把缓存目录改到用户可控的位置：composer config -g cache-dir ~/composer-cache

PHP version does not satisfy 或 Call to undefined function

很多人只看php -v显示8.2就以为万事大吉，但CLI和Web跑的可能不是同一个php.ini，扩展也可能没开全。

• 跑一下php -m | grep -E "curl|json|openssl|phar|zlib"，缺哪个就去php.ini里取消对应;extension=xxx的注释
• 确认allow_url_fopen = On，否则Composer没法远程拉取包信息
• Windows用户要留个心：XAMPP/MAMP的CLIphp.ini路径通常在php\phpX.X.X\目录下，和Apache用的不是同一个
• 用php --ini查真实加载路径，用php -i | grep 'Loaded Configuration File'核实一遍
• 系统时间偏差超过5分钟也会导致TLS握手失败，跑date检查并校准

真正磨人的其实是PHP CLI和Web服务器加载的配置不一致——比如php -m显示有openssl，但php -i显示CLI加载的是另一个php.ini。这种差异比网络问题更难察觉，也更容易导致安装到一半静默失败。