composer config -g repo.packagist 命令没生效是因为键名必须为单数repo.packagist、中间type值必须显式写composer、url须https且末尾带/，三者缺一即静默回退官方源；还需检查项目级repositories是否覆盖及缓存是否清除。
composer config -g repo.packagist 命令为什么没生效
它根本不会报错，但 composer install 依然连 packagist.org ——这不是网络慢，是命令写错了三个硬性条件中的任意一个，Composer 就静默忽略整条配置。
-
repo.packagist必须一字不差：写成repos.packagist、repository.packagist或mirror全部无效 - 中间的
composer是type值，不是可选参数，也不能替换成composer.org或省略 - URL 必须是 HTTPS 且末尾带
/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致请求路径拼成/composerpackages.json，直接 404）
验证是否真写进去了？别信“命令跑完就 OK”，运行：composer config -g repo.packagist。输出必须是完整 JSON，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或仍是 https://packagist.org，说明根本没写成功。
项目级配置覆盖全局时怎么处理
只要项目根目录的 composer.json 里有 repositories 字段（哪怕只是 "repositories": []），全局镜像就完全失效——这是 Composer 的硬编码优先级，不是 bug。
- 检查当前项目是否已启用项目级镜像：
composer config repo.packagist（不带-g），有输出就说明项目自己写了 -
composer config repo.packagist composer https://mirrors.aliyun.com/composer/会**全量替换**整个repositories字段，把你原有的私有源（比如 Git VCS 源）直接清空 - 想保留私有源又加镜像？手动编辑
composer.json，确保repositories是数组，首位加{"packagist.org": false}，第二位再放阿里云镜像对象，并保留其他自定义源
CI/CD 或宝塔这类多用户环境，composer config -g 默认写的是你当前终端用户的配置，而 Web 进程常以 www 用户运行，权限链断了。稳妥做法是统一用项目级配置。
换镜像后 composer install 报 hash 不匹配
这不是镜像地址问题，是旧 composer.lock 文件里记录的包哈希和 dist URL 还指向官方源，切换镜像后 Composer 去阿里云找同名 zip，但内部路径映射不同，校验必然失败。
- 必须删掉项目里的
vendor/目录 - 必须删掉
composer.lock文件 - 再执行
composer install（注意不是update）——只有install才会按新镜像 + 新 lock 重建依赖树
漏掉任意一步，都会卡在 hash mismatch 或反复下载失败。尤其团队协作时，有人提交了旧 lock 文件，其他人拉下来直接复现这个问题。
宝塔、Docker、GitHub Actions 里镜像总不生效
这些环境根本不读你本地 ~/.composer/config.json，全局配置在这里形同虚设。
- 宝塔面板里 PHP CLI 默认禁用
proc_open、putenv、pcntl_signal，Composer 启动即崩溃，根本走不到镜像环节——先去「PHP 管理」→「禁用函数」里删掉它们 - Docker CI 中，得在构建阶段显式执行配置命令：
RUN composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，且确保该命令在composer install之前 - GitHub Actions 默认用 runner 用户，
composer config -g写的是 runner 用户的 home 目录，没问题；但若用了自托管 runner 且未清理缓存，仍要composer clear-cache
真正容易被忽略的是缓存残留：即使改了镜像，Composer 仍可能从本地缓存读取旧元数据。每次换源后，务必 composer clear-cache，再删 vendor/ 和 composer.lock，三步缺一不可。
