Composer config -g repo.packagist 没生效是因为三个硬性条件任一缺失：键名必须为单数 repo.packagist（非 repos.packagist）、type 值必须显式写 composer、URL 必须 HTTPS 且末尾带 /；任一出错即静默回退官方源，验证需输出完整 JSON 对象。
composer config -g repo.packagist 为什么没生效
命令静默失败，不是 Composer 坏了，而是三个硬性条件漏掉任意一个：repo.packagist 键名拼错（比如写成 repos.packagist 或 packagist.org）、composer 这个 type 值被省略、URL 末尾缺 /。这三处任一出错，Composer 2.x 就会自动 fallback 到官方源，不报错也不提示。
验证是否写入成功，只看这一条命令输出：composer config -g repo.packagist。必须返回类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON 对象。空、null、报 Key does not exist，或者只返回 URL 字符串（新版行为），都说明配置失败。
- Windows 用户执行后需重启终端，否则配置缓存可能未刷新
- 别手改
~/.composer/config.json—— 权限、JSON 格式、路径错误都会导致静默失效 -
repo.packagist是固定键名，Composer 1.x 的repos.packagist在 2.x 已废弃
项目级镜像配置覆盖全局设置怎么办
项目目录下运行 composer config repo.packagist（不带 -g）有副作用：它会全量替换 composer.json 中的 repositories 字段，而不是追加。如果项目原本已定义私有 Git 源或其它仓库，执行后整个 repositories 会被清空，只剩镜像源。
真正安全的做法是手动编辑 composer.json，确保：
-
"repositories"是数组格式，首位对象为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 已有私有源保留在同一数组中，顺序无关
- 根节点不要写
"packagist": false或"packagist.org": false，否则基础 PHP 扩展校验会失败 - 改完必须删掉
vendor/和composer.lock，再跑composer install（不是update）
换镜像后 still stuck at “Loading composer repositories”
这不是网络问题，而是请求压根没发到镜像站。大概率是项目级 repositories 配置覆盖了全局设置，或者 composer.json 里写了禁用语句。
排查步骤很直接：
- 分别运行
composer config -g repo.packagist和composer config repo.packagist，看哪一层返回了 URL - 检查
composer.json是否存在"repositories"字段，尤其搜"packagist.org": false - 临时验证镜像可用性：
curl -I https://mirrors.aliyun.com/composer/packages.json，返回200 OK才算服务正常 - 加
-vvv跑一次composer install，日志里搜GET https://—— 看实际请求的是mirrors.aliyun.com还是packagist.org
CI/宝塔/Docker 环境里全局配置为啥不起作用
全局配置写在 ~/.composer/config.json，但它只对当前用户生效。宝塔默认以 www 用户运行，GitHub Actions 用 runner 用户，Docker 容器里甚至没有 ~/.composer 目录 —— 你配的 repo.packagist 根本读不到。
解决方法很简单：
- 先确认实际执行用户，比如
whoami或查构建日志里的 UID - 针对性配置：
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 更可靠的做法是坚持项目级配置，把镜像写进
composer.json并提交 Git，团队和 CI 行为一致 - 已有
composer.lock的项目首次切镜像，必须删vendor/和composer.lock，否则哈希校验失败
最易被忽略的一点：镜像地址末尾那个 / 不是风格问题，是协议级要求；composer config 命令里的 composer 也不是可选参数，是 type 字段值。少一个字符，整个配置就形同虚设。
