“file could not be downloaded”或卡在“Loading composer repositories”基本是网络链路问题，需切阿里云镜像、清缓存、删vendor和composer.lock，并用-vvv验证真实请求地址。
报“file could not be downloaded”或卡在“Loading composer repositories”
这基本是网络链路问题，不是本地 PHP 或 Composer 本身坏了。Packagist.org 直连在国内几乎不可用，TLS 握手失败、DNS 污染或连接中断都会触发这类错误，表现就是命令卡住、无响应，或报 file could not be downloaded。
- 立刻切阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（注意第三参数composer不能省，URL 末尾必须带/） - 切完必须清缓存：
composer clear-cache；Windows 用户还得手动删%LOCALAPPDATA%\Composer\cache下的repo子目录 - 删掉
vendor/和composer.lock——composer.lock里硬编码了旧源地址，不清它，换源也白搭 - 验证是否真走了镜像：
composer install -vvv 2>&1 | head -n 10 | grep Downloading，第一行 URL 才是真实请求地址；只看composer config输出没用
报“Could not find package”但包名确认无误
这不是拼写错误，而是 Composer 根本没拿到 packages.json——它连镜像的索引文件都没拉下来，后续所有解析都无从谈起。常见表现是 composer install -vvv 输出里压根不出现 Downloading.*.json。
- 先验证镜像基础可用性：
curl -I https://mirrors.aliyun.com/composer/packages.json必须返回HTTP/2 200和Content-Type: application/json；若返回 404、HTML 页面或空响应，说明镜像未同步或 URL 错误 - 确认镜像 URL 是 HTTPS 且结尾带
/：写成https://mirrors.aliyun.com/composer（缺斜杠）会导致 Composer 拼出非法路径/composerpackages.json，必然 404 - 别信
composer config -g repo.packagist的输出——它只告诉你“写了什么”，不等于“正在用什么”。真正生效的得看composer diagnose输出中Repo packagist.org:那一行 - 如果项目
composer.json里有"repositories"字段（哪怕只是空数组[]），全局镜像配置就完全失效。临时解决：composer config --unset repositories
报“Permission denied”却没提示具体路径
错误里带路径的那一行才是关键。别管“权限不足”这种模糊提示，直接盯终端输出中明确写出失败路径的那行——比如 failed to open stream: Permission denied in /home/user/project/vendor/autoload.php，那 vendor/ 就是问题所在。
- 查归属：
ls -ld vendor/、ls -ld composer.lock、ls -ld $(composer config --global cache-dir)；只要任意一行第一列显示root，就确认是所有权错配 - 修复归属：
sudo chown -R $USER:$USER vendor/ composer.lock；全局缓存同理：sudo chown -R $USER:$USER $(composer config --global cache-dir) - 某些 CI/CD 或宝塔环境，你用
root配的全局镜像，但实际执行的是www用户，得用sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
执行 composer 命令提示 “command not found”
这不是没装上，而是没加到系统 $PATH。安装脚本默认把 composer.phar 放到了当前目录，没设为全局命令。
- 手动移动并重命名：
sudo mv composer.phar /usr/local/bin/composer（Linux/macOS）；Windows 则需把composer.phar移到%PROGRAMFILES%\Composer\并添加该路径到系统环境变量 - 验证是否生效：
composer --version；若报错Could not open input file: composer.phar，说明路径没生效，重新检查$PATH或环境变量 - 不要长期用
php composer.phar代替composer，否则所有项目调用都要多敲php，且 IDE/CI 工具可能识别失败
composer.lock 和全局缓存的耦合关系——换镜像后不清锁文件，Composer 会坚持按旧地址去拉 provider，结果反复 404；而清缓存又常被 Windows 用户漏掉 %LOCALAPPDATA% 下的手动清理。这两步缺一不可。 
