Composer install卡在Downloading或Loading repositories，90%因未正确配置国内镜像源：键名必须为repo.packagist（单数）、type值必填composer、URL须为HTTPS且末尾带/；验证需同时满足config输出正确JSON及install -vvv日志显示镜像路径。
composer install 卡在 Downloading... 或 Loading composer repositories，基本可以确定没配对中文镜像——不是网速问题，是默认连 packagist.org 导致 DNS 解析慢、TLS 握手卡、首字节延迟高甚至 503 超时。
全局镜像配置为什么经常失效
命令看似简单，但三处细节错一个就静默回退到官方源：repo.packagist（不能是 repos.packagist 或 packagist.org）、中间的 composer（这是 type 值，不是可选参数）、URL 必须是 HTTPS 且末尾带 /。
-
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/✅ 正确 -
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/❌ 多个 s，完全无效 -
composer config -g repo.packagist https://mirrors.aliyun.com/composer/❌ 少composer类型声明，旧版 fallback 默认源 -
composer config -g repo.packagist composer http://mirrors.aliyun.com/composer/❌ HTTP 被 Composer 2.0+ 拦截
验证是否生效，只看这一条：composer config -g repo.packagist。输出必须是完整 URL 字符串或 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、报 Key not found，说明根本没写进去。
项目级配置才是团队和 CI 的真实解法
全局配置只对当前用户生效，而宝塔以 www 用户运行、GitHub Actions 用 runner 用户、Docker 容器里可能是 app 用户——它们都读不到你本地 root 或 admin 的配置。
- 进项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加-g） - 该命令会自动向
composer.json的repositories字段安全追加，不覆盖已有私有源 - 如果
composer.json已有"repositories": []，命令会报错；此时需先手动改成"repositories": {}再运行 - 千万别写
"packagist": false，否则基础扩展（如ext-json）校验失败，composer install直接中断
改完后必须删掉 vendor/ 和 composer.lock，再跑 composer install，否则旧 lock 文件里的哈希可能与镜像元数据不匹配。
立即学习“PHP免费学习笔记（深入）”；
换源后仍卡在 Resolving dependencies 怎么办
镜像只加速下载，不解决依赖解析阶段的卡顿。composer update 卡几十秒甚至几分钟，和镜像无关，得查本地环境：
- PHP 内存不足：默认 128M 不够，临时加
COMPOSER_MEMORY_LIMIT=-1 - Xdebug 启用中：会让解析慢 5–10 倍，用
php -d xdebug.mode=off $(which composer) install临时禁用 -
config.platform.php与实际 PHP 版本不匹配：比如写"php": "7.4"却在 PHP 8.5.5 上运行，触发降级查找逻辑 - 老旧
composer.lock：先试composer update --lock轻量更新，避免全量重算
另外，如果项目用了已废弃的 fxp/composer-asset-plugin（常见于老版 Yii2），它不走 Composer 镜像配置，会额外请求 Bower/NPM 源——这些源没国内镜像，得升级框架或迁移到 npm/yarn。
临时验证某个镜像是否可用
不想动任何配置，又想快速确认镜像是否有效？直接加参数：
composer create-project topthink/think tp-demo --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/composer install --repository-url=https://mirrors.cloud.tencent.com/composer/
这种用法只对当次命令生效，适合排查问题或测试新镜像。注意 URL 同样要带末尾 /，否则部分版本会拼接出错返回 404。
镜像同步本身有延迟，阿里云/腾讯云通常 5 分钟内，清华源底部会显示“最后更新时间”。如果某个包刚发布不到一小时，在镜像里找不到是正常的，别急着关掉官方源 fallback 机制。
