Composer镜像配置失败主因是命令写错：键名必须为repo.packagist（单数小写）、type值必填composer、URL末尾必须带/，缺一即静默回退至packagist.org。
Composer 默认直连 packagist.org，在国内环境下大概率卡在 Loading composer repositories 或 Downloading，不是你网络差，是源没配对——配错一个字符就等于没配。
composer config -g repo.packagist 命令为什么没生效
几乎全是这三个硬伤导致的静默失效：
-
repo.packagist键名写成repos.packagist（多一个 s）或packagist.org（少repo.前缀） - 漏掉中间的
composertype 值，比如写成composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - URL 末尾缺斜杠
/，例如https://mirrors.aliyun.com/composer❌，必须是https://mirrors.aliyun.com/composer/✅
验证是否真写进去了，只看这一条命令输出：composer config -g repo.packagist。输出为空、null、报 Key does not exist，或者只返回一串 URL 字符串（新版 Composer 行为），都说明配置失败。别信“命令没报错就成功了”。
项目级镜像配置如何避免覆盖私有仓库
团队项目常带私有包源，手动改 composer.json 极易格式出错或误删已有 repositories。安全做法是让 Composer 自动合并：
立即学习“PHP免费学习笔记（深入）”；
- 进项目根目录（含
composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不加-g） - 如果原
composer.json是"repositories": {}，它会自动转成数组并追加 packagist 条目 - 如果原
repositories已是数组，它会在末尾插入新对象，不碰已有私有源 - 千万别手动写
"packagist": false，这会让基础扩展（如ext-json）校验失败
改完立刻运行 composer update --lock，确保 composer.lock 记录的是新镜像的元数据哈希，否则后续 install 仍可能 fallback 到官方源。
宝塔/CI 环境里全局配置为啥不起作用
全局配置写在 ~/.composer/config.json，但只对当前用户生效。宝塔默认用 www 用户跑 PHP，GitHub Actions 用 runner 用户，它们根本读不到你本地 root 或 admin 的配置。
- 查清实际执行用户：
whoami或看日志 UID - 给对应用户单独配：
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - Docker 构建时，
-g配置不持久，必须把镜像写进composer.json才能每次生效
换源后首次 composer install 报 hash does not match 或 package is not installed？直接删掉 vendor/ 和 composer.lock，再重装——旧 lock 文件记录的是官方源的哈希，和镜像元数据不兼容。
镜像只加速下载和元数据拉取，不解决 Resolving dependencies 卡顿；那个阶段慢，得看 PHP 版本、config.platform.php 设置、以及 lock 文件是否老旧。
