必须配置阿里云 Composer 镜像，因 packagist.org 在国内 DNS 解析慢、TLS 不稳定、无 CDN，导致元数据请求频繁超时；命令需严格写为 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，缺一不可。
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 这条命令执行完，90% 的国内 Composer 卡顿问题就解决了——不是“可能有效”，而是必须做，否则 composer install 卡在 Loading composer repositories 是常态，不是偶然。
为什么必须配镜像，而不是等它自己好
packagist.org 在国内 DNS 解析慢、TLS 握手不稳定、缺少就近 CDN 节点，导致元数据请求（非 ZIP 包下载）频繁超时或 503。这不是网络波动，是持续性不可用。实测未配镜像时，composer install 停在该阶段超过 5 分钟不报错，只空转。
composer config -g repo.packagist 必须写对的三个细节
写错命令不会报错，但完全无效：
-
repo.packagist不能写成repos.packagist（多一个 s 就失效） -
composer是 type 值，不能省略——写成composer config -g repo.packagist https://...会 fallback 到官方源 - URL 必须以
https://开头，且末尾带斜杠/；http://或缺斜杠会导致 404 或静默回退
验证是否真生效，别靠“感觉快了”
运行 composer config -g repo.packagist，输出必须是类似这样的 JSON：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
如果返回空、null、或报错 Could not open input file: composer，说明：
– composer 命令没进 PATH
– 当前用户无权写入配置目录（Linux/macOS 可 chown -R $USER ~/.composer）
– 在宝塔/Docker 里执行时用了错误用户（比如应 sudo -u www composer config -g ...）
项目级配置比全局更可控，尤其团队协作时
全局配置容易被覆盖或引发 CI 不一致。项目级写法更透明：
- 进项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g） - 它会向
composer.json的repositories字段自动写入"packagist"键，不破坏已有私有源 - 换源后首次
composer install报 hash 不一致？直接删掉vendor和composer.lock重来，别尝试 patch
镜像只解决元数据拉取和包分发，不干预依赖解析逻辑。如果 composer update 卡在 Resolving dependencies，那和镜像无关，得查 composer.json 冲突或本地 PHP 环境。
