composer config -g repo.packagist 能生效，但90%配置失败是因未满足三硬性条件：键名必须为单数repo.packagist、第二参数必填composer（type值）、URL须为HTTPS且末尾带/，缺一即静默回退官方源。
composer config -g repo.packagist 这条命令能生效，但**90% 的人配不成功不是因为网络，而是命令写错了三个硬性条件**——漏掉任意一个都会静默失败，不报错、不提示，只让你继续卡在 Loading composer repositories。
为什么 composer config -g repo.packagist 总是不生效
它不是“差不多对就行”的命令，而是严格校验三要素：
-
repo.packagist是唯一合法键名：不能写成repos.packagist（多一个 s）、packagist.org（少repo.）、aliyun（Composer 不识别） - 中间的
composer是 type 值，不可省略：缺了它，Composer 2.x 会自动 fallback 到官方源，且完全不提示 - URL 必须是 HTTPS + 末尾带斜杠：比如
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠 → 请求路径变成/composerpackages.json→ 404）
验证是否写入成功？直接运行：composer config -g repo.packagist
输出应为完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
如果返回空、null 或报 Key not found，说明根本没写进去。
宝塔、CI、Docker 里全局配置为啥总失效
全局配置写在 ~/.composer/config.json，但「谁在跑命令」决定读哪个文件：
- 你在终端用
root执行了composer config -g，但宝塔「一键部署」是以www用户运行的，它读的是/home/www/.composer/config.json，根本看不到root的配置 - CI 脚本里写了
sudo composer config -g，结果写进了root配置，而构建容器里实际用的是runner用户，照样失效 - PHP CLI 模式下如果
disable_functions禁用了proc_open或putenv，composer config -g会直接报错或静默失败（检查php.ini并重启服务）
项目级配置才是团队和 CI 的真实解法
进项目根目录，运行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/
（注意：去掉 -g）
- 它会自动往
composer.json的repositories字段安全追加，不覆盖已有私有源 - 前提是
repositories当前是对象结构（如"repositories": {}），如果是数组（"repositories": []），命令会报错，得先手动改成对象 - 别手写
"packagist.org": false—— 这会彻底关掉官方源，一旦镜像临时不可用，composer install直接失败；正确做法是确保镜像 URL 正确，且不加这行 - 改完必须删掉
vendor和composer.lock再重装，否则旧 lock 文件里的 hash 可能和镜像元数据不匹配
换镜像后还是卡？先看是不是真卡在下载环节
执行 composer require monolog/monolog -vvv，观察终端输出：
- 重点看 HTTP 请求地址是否命中你配的镜像域名（如
mirrors.aliyun.com） - 有没有出现
Connection timed out或curl error 28（说明 DNS 或网络层不通，不是 Composer 配置问题） - 是否意外加载了
packagist.org的packages.json（说明镜像没生效，或"packagist.org": false错误地屏蔽了所有源）
镜像只是代理，不是魔法。真正卡住的时候，先 ping mirrors.aliyun.com 和 curl -I https://mirrors.aliyun.com/composer/packages.json 看底层通不通，比反复调 composer 参数更省时间。
