镜像配置是解决composer install卡在Downloading的刚性前提；失效主因是键名错（如repos.packagist）、漏type值composer、URL缺末尾/，任一错误均静默回退至packagist.org。
镜像配置不是“锦上添花”，而是解决 composer install 卡在 Downloading 的刚性前提——90% 的慢，根源是还在直连 packagist.org。
为什么 composer config -g repo.packagist 没生效
这不是镜像不行，而是三个硬性条件漏掉任一：键名写成 repos.packagist（多一个 s）、漏掉 composer 这个 type 值、URL 末尾没加 /。Composer 2.x 遇到这三类错误会静默 fallback 到官方源，不报错也不提示。
- 验证是否成功：运行
composer config -g repo.packagist，输出必须是完整 JSON，形如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 空输出、
null、只返回 URL 字符串（新版行为）、或返回https://packagist.org，都说明配置失败 - Windows 用户配置文件路径是
%APPDATA%\Composer\config.json，别手写，用命令写入更安全
项目级配置如何不破坏私有仓库
执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g）时，它会尝试自动合并进 composer.json 的 repositories 字段——但前提是该字段是对象（{}），不是数组（[]）；否则会直接覆盖整个字段，清空你已有的私有 Git 源。
- 已有
"repositories": {}：命令会安全追加packagist子项 - 已有
"repositories": []：命令会报错，需先手动改成对象格式 - 千万别写
"packagist.org": false在repositories内部——这会导致基础包（如php、ext-json）校验失败 - 改完后务必运行
composer update --lock，确保composer.lock记录新源地址
宝塔/CI 环境里全局配置为啥不起作用
全局配置写在当前用户的 ~/.composer/config.json，但它只对那个用户生效。宝塔「一键部署」、PHP 管理器、Jenkins 构建任务默认以 www、jenkins 或 runner 用户运行，根本读不到你登录 shell 时配的 root 或个人用户配置。
- 排查方法：在对应环境里先确认执行用户（比如
whoami或查日志 UID），再用该用户身份执行composer config -g repo.packagist - 给
www用户配：执行sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 脚本中不要依赖全局配置，改用临时参数：
composer install -vvv --repository-url=https://mirrors.aliyun.com/composer/
怎么确认镜像真的在用
光看命令执行成功没用，得看实际请求是否打到镜像域名。最可靠的方式是加 -vvv 参数观察日志：
- 运行
composer install -vvv，搜索日志里的GET请求 URL，确认是https://mirrors.aliyun.com/composer/...而非https://packagist.org/... -
composer diagnose只能告诉你“Repo packagist.org is default”，不能反映真实请求路径，别全信 - 已有
composer.lock的项目首次换镜像，大概率因哈希不匹配失败；删掉vendor和composer.lock再重装才稳妥 - 某些包（如 GitHub 直链、私有 Git 仓库）不走镜像，
composer.lock里若仍存原始dist.url，就得删 lock 文件重来
