composer全局镜像配置失效的根本原因是键名必须为repo.packagist（单数，不可多s或加.org）、必须加-g参数、url末尾必须带/，三者缺一即静默回退官方源；验证需输出完整json对象。
直接配全局镜像就行，但必须用 repo.packagist 键名、带 -g 参数、URL 末尾加 /，否则看似成功实则无效。
为什么 composer config -g repos.packagist.org 不生效？
这是最常踩的坑：键名写错。Composer 2.5+ 只认 repo.packagist（注意是 repo，不是 repos，也没有 .org 后缀）。写成 repos.packagist.org 或 packagist.org 都会静默失败——命令返回成功，但配置根本不写入。
-
composer config -g repo.packagist输出为空，说明键名错了 - 正确命令只有一条：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ -
composer是 type 值，不能省；https://mirrors.aliyun.com/composer/结尾的/也不能少，否则请求路径拼错导致 404
配完还是连 packagist.org？检查项目级覆盖
全局配置优先级最低。只要项目根目录下 composer.json 里有 "repositories" 字段（哪怕空对象 {}），就会完全屏蔽全局镜像。
- 进项目目录，运行
composer config --list | grep repositories，有输出就说明被覆盖了 - 删掉
composer.json里的"repositories"块，或改成指向镜像地址：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 旧的
composer.lock文件里硬编码了原始源地址，必须删掉它和vendor/目录，再跑composer install
验证镜像真在用，别只信 config 输出
composer config -g repo.packagist 返回 URL 只代表写入成功，不代表网络请求真发到了镜像站。
- 先清缓存：
composer clear-cache - 新建空目录，执行：
composer init -n && composer require monolog/monolog --no-install -vvv 2>&1 | grep "GET https" - 看到
GET https://mirrors.aliyun.com/composer/packages.json才算真正生效；若出现packagist.org或Could not resolve host，说明 DNS、代理或公司防火墙在拦截
M1/M2 Mac 上特别容易卡在哪？
Homebrew 安装的 composer 包自 2023 年起已弃用，在 Apple Silicon 上几乎必出问题：命令找不到、权限拒绝、版本卡在 2.2.x。必须用官方脚本安装，并确保路径和权限对齐。
- PHP 必须是
/opt/homebrew/bin/php（ARM64 原生），不是/usr/bin/php或 Rosetta 转译版 - 执行
curl -sS https://getcomposer.org/installer | php生成composer.phar - 移至
sudo mv composer.phar /opt/homebrew/bin/composer，再sudo chmod +x /opt/homebrew/bin/composer - 确认
which composer输出是/opt/homebrew/bin/composer，否则 PATH 没生效
最容易被忽略的是：CI 环境（如 GitHub Actions）里，composer config -g 和后续 composer install 必须在同一个用户上下文执行；Web 服务（如 PHP-FPM）若以 www 用户运行，却用 root 配了镜像，照样读不到。
