Composer镜像配置必须同时满足三个硬条件：键名严格为repo.packagist（单数）、中间type值必须显式写composer、URL须HTTPS且末尾带/，任一不符即静默回退官方源；验证需输出完整JSON对象。
配镜像源不是改个 URL 就完事，composer config -g repo.packagist 命令静默失败才是常态——漏掉 -g、键名写成 repos.packagist、URL 少末尾 /，任一出错，Composer 就当没这回事，继续连 https://packagist.org，还不报错。
为什么 composer config -g repo.packagist 总是“看起来成功，实际没用”
它不报错，但也不生效。根本原因就三点：
-
repo.packagist是唯一合法键名：写成repos.packagist（多一个 s）、repository.packagist或packagist.org全部被忽略 - 中间的
composer是必填的type值，不是注释，不能省略，也不能写成composer.org - 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、或仍显示 https://packagist.org，说明根本没写成功。
全局配置 vs 项目级配置：谁在真正起作用？
全局配置（加 -g）只写入当前用户的 ~/.composer/config.json，但在宝塔、GitHub Actions、Docker 容器里，PHP 进程往往以 www、runner 等非登录用户身份运行，压根读不到你的配置。
立即学习“PHP免费学习笔记（深入）”；
项目级配置才可靠：
- 进项目根目录（含
composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 它会自动在
composer.json顶层写入"repositories"字段，key 固定为"packagist"，不会覆盖已有私有源 - 但注意：
"repositories": []（数组）会导致命令静默失败；需先手动改成"repositories": {}（空对象）再重试 - 一旦
composer.json里存在"repositories"字段，全局配置就完全失效
换源后依然卡在 “Loading composer repositories”？
这不是镜像地址问题，而是 Composer 还在用旧缓存和旧 composer.lock 里的元数据。
- 先运行
composer diagnose，确认 “Repo:” 行显示的是你配的镜像域名（如mirrors.aliyun.com） - 立刻清缓存：
composer clear-cache - 删掉
vendor/和composer.lock，再跑composer install（不是update） - 如果
composer install仍卡住，检查是否启用了xdebug或 PHP 内存不足（临时加COMPOSER_MEMORY_LIMIT=-1测试）
多个镜像源怎么配才真正起作用
Composer 不并行查源，而是按 "repositories" 数组顺序逐个尝试——第一个能返回包信息的源就用它，后面全跳过。
- 把国内镜像放首位，官方源放最后兜底，才是有效多源
- 别手写
"packagist": false—— 这会彻底关掉基础包源，导致require失败 - 临时验证某个镜像是否可用？用
--repository-url参数：composer update --repository-url=https://mirrors.aliyun.com/composer/（仅当前命令生效）
最常被忽略的一点：即使命令执行无报错，也必须用 composer config -g repo.packagist 实际输出来验证；哪怕只差一个斜杠，Composer 就已静默回退到官方源，而你还在等它响应。
