composer config -g repo.packagist 总不生效是因为必须同时满足三个硬性条件：键名必须为单数 repo.packagist（非 repos）、第二个参数必须显式写 composer（type 值）、url 必须 https 且末尾带 /；任一缺失即静默回退官方源，且不报错。
镜像源配不对，composer install 就永远卡在 Loading composer repositories —— 不是网络差，是配置静默失效，连报错都没有。
为什么 composer config -g repo.packagist 总不生效
90% 的失败不是网络问题，是命令漏掉三个硬性条件：
-
repo.packagist不能写成repos.packagist（多一个s就完全无效） - 中间的
composer是type值，必须显式写出，不能省略 - 镜像 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 或报错，说明没写对，立刻重试。
composer config repo.packagist（不加 -g）在项目根目录执行时的坑
这条命令看似简单，但实际行为和很多人想的不一样：
- 它会**全量替换**
composer.json中的repositories字段，不是追加 —— 如果项目已有私有 VCS 源，这条命令会把它清空 - 要求
repositories必须是对象（{}），不能是数组（[]）；如果是数组，命令直接报错，需先手动改成空对象 - 改完后必须删掉
vendor/和composer.lock，再跑composer install；composer update没用，它照着旧 lock 文件里的 dist URL 下载
安全做法：手动编辑 composer.json，在顶层 repositories 数组首位插入阿里云镜像对象，并确保 "packagist.org": true（千万别设为 false，否则基础包全拉不到）。
CI/CD、宝塔、Docker 环境里镜像为啥不起作用
全局配置（-g）只写进当前用户的 ~/.composer/config.json，而这些环境默认以非登录用户运行：
- GitHub Actions 用
runner用户 - 宝塔部署脚本默认用
www用户 - Docker 容器内可能根本没你的家目录
所以 CI 脚本里别依赖全局配置，直接加参数：composer install --repository-url=https://mirrors.aliyun.com/composer/；宝塔里配镜像，得用 sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
换源后仍卡在 Resolving dependencies 怎么办
镜像只加速元数据下载和 ZIP 包下载，不参与依赖解析。如果你发现 composer update 卡在这一步超过 10 秒，问题和镜像无关：
- 检查
composer.json是否写了过于宽泛的版本约束（如"php": "^7.4 || ^8.0"），导致解析器穷举组合 - 确认
require-dev里没塞太多未收敛的 dev 分支依赖 - 临时禁用镜像验证根源：
composer clear-cache && composer install --no-cache -vvv 2>&1 | grep "Downloading"，看真实请求域名是否变成镜像地址
真正起作用的永远是 composer.json 里 repositories 数组的顺序 —— 镜像必须放第一位，官方源放最后兜底；任何手改格式错误、字段嵌套错层、或 "packagist.org": false 这类粗暴屏蔽，都会让整个依赖链崩掉。
