Composer install卡在Loading composer repositories或Downloading，90%因镜像配置错误：键名必须为repo.packagist（单数）、type值必填composer、URL须含末尾/；验证需同时满足config输出正确JSON及install -vvv日志显示镜像路径。
composer install 卡在 Loading composer repositories 或 Downloading，90% 不是网络差，而是镜像源没配对——命令写错、缓存没清、URL 少斜杠，三者任一出问题都会静默 fallback 到 packagist.org。
为什么 composer config -g repo.packagist 总是不生效
这条命令不是“执行了就完事”，它必须同时满足三个硬性条件，缺一不可：
-
repo.packagist是唯一合法键名（注意是repo单数，不是repos；也不能写成packagist.org） -
composer是必填的type值，不是可选参数（漏掉它，Composer 2.0+ 直接回退官方源） - URL 必须是完整 HTTPS 地址，且末尾带
/（比如https://mirrors.aliyun.com/composer/；少斜杠会拼出/composerpackages.json导致 404）
常见错误写法：composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/（多 s）、composer config -g repo.packagist https://mirrors.aliyun.com/composer/（缺 type）、composer config -g repo.packagist composer https://mirrors.aliyun.com/composer（缺 /）。
验证镜像是否真走通，只看两处输出
别信“命令没报错”，要看实际请求地址是否被替换：
- 运行
composer config -g repo.packagist，输出必须是完整 URL 字符串（如https://mirrors.aliyun.com/composer/）或标准 JSON 对象（含"type": "composer"和该 URL）；返回null、空值、https://packagist.org或报错，说明配置失败 - 再跑一次
composer install -vvv，最后几行必须出现类似Reading packages.json from cache at /https---mirrors-aliyun-com-composer/；如果还看到packagist.org/packages.json，就是 fallback 了
全局配置 vs 项目级配置：哪个更稳
全局看着省事，但 CI/CD、Docker、宝塔等环境常因用户权限读不到 ~/.composer/config.json，导致配置失效。项目级反而更可靠：
立即学习“PHP免费学习笔记（深入）”；
- 进项目根目录，执行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加-g） - 它会自动向
composer.json的repositories字段追加"packagist"条目，不覆盖已有私有源（前提是原repositories是对象结构，不是数组） - 如果
composer.json里已有"repositories": []（数组），该命令会失败；需先手动改成"repositories": {}再运行 -
composer.json可提交 Git，团队成员拉代码后行为一致
换源后仍失败？先清缓存再重试
缓存没清，90% 的“换源无效”就出在这里：
- 执行
composer clear-cache—— 这步跳过，等于白配 - 如果还卡住，删掉
vendor/和composer.lock，再跑composer install - 若项目中显式写了
"packagist.org": false，会直接屏蔽全局镜像，此时必须在项目级repositories中显式声明packagist镜像项
镜像只加速元数据索引（packages.json）拉取，不托管 ZIP 包本身；真正影响下载速度的，是 Composer 2.9.6 的并行下载能力 + 镜像响应延迟。所以别指望“换源=秒装”，但能确保“找得到包、不超时、不 fallback”。
