Composer镜像配置失效主因是repo.packagist键名错（如多s）、漏写type值“composer”、URL末尾缺/，三者任一出错即静默回退官方源；验证须执行composer config -g repo.packagist，输出必须为完整JSON或URL字符串，空/null即失败。
Composer 卡在 Downloading... 或报 could not find package，基本不是你网络差，而是还在直连 packagist.org——换镜像不是“锦上添花”，是必须做的第一步。
composer config -g repo.packagist 命令为什么没生效
这条命令静默失败的概率远高于成功，原因就三个硬伤：
-
repo.packagist写成repos.packagist（多一个 s），Composer 2.x 完全忽略，不报错也不提示 - 漏掉中间的
composer——它不是可选参数，是 type 值，必须显式写出 - URL 末尾没加
/，比如写成https://mirrors.aliyun.com/composer，会导致路径拼接错误，部分版本直接 fallback 到官方源
验证是否真生效，只看这一条：composer config -g repo.packagist。输出必须是完整 URL 字符串（如 https://mirrors.aliyun.com/composer/）或标准 JSON 对象（如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}）。空、null、报 Key does not exist，说明配置根本没写进去。
宝塔/CI 环境里全局配置为啥不起作用
全局配置写在 ~/.composer/config.json，但它只对当前用户生效。宝塔后台默认以 www 用户运行，GitHub Actions 用 runner 用户，它们根本读不到你本地 root 或 admin 的配置。
立即学习“PHP免费学习笔记（深入）”；
- 查实际执行用户：在宝塔任务脚本里加
whoami，或看日志里的 UID - 给对应用户配镜像：比如宝塔用
www，就执行sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 场景更推荐项目级配置，避免依赖宿主环境
项目级配置怎么安全追加不破坏私有源
进项目根目录（含 composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不加 -g）。
- 如果
composer.json原本没有repositories字段，命令会自动创建并写入标准格式 - 如果已有
"repositories": {}（空对象），命令会 merge 进去；如果是"repositories": []（空数组），命令会报错，需先手动改成对象 - 千万别手写
"packagist.org": false——这会彻底关掉兜底机制，镜像临时不可用时，composer install直接失败 - 改完必须删掉
vendor/和composer.lock，再跑composer install，否则旧 lock 文件里的哈希可能和镜像元数据不匹配
镜像只加速下载，不解决 Resolving dependencies 卡顿；换源后还慢，得查 PHP 内存、Xdebug、platform 版本匹配这些真实瓶颈。真正容易被忽略的是：不同用户、不同环境、不同 Composer 版本对配置格式的容忍度差异极大，靠猜和试不如靠 composer config -g repo.packagist 看一眼输出。
