Composer全局镜像配置失效主因是键名错（应为单数repo.packagist）、缺type值“composer”、URL末尾无/，三者任一出错均静默回退官方源；项目级repositories字段会完全屏蔽该配置。
国内用 Composer 不配镜像，基本等于没法装依赖——不是慢，是大概率失败。超时、403、卡在 Downloading，根源全在直连 packagist.org。配镜像不是“提速技巧”，而是能跑起来的前提。
composer config -g repo.packagist 命令为什么总不生效
这条命令写错一个字符就静默失效，不报错但完全不走镜像。最常见错误有三个：
-
repo.packagist写成repos.packagist（多一个s）——键名错误，Composer 忽略该配置 - 漏掉中间的
composertype 参数：正确是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，少掉那个composer就 fallback 回官方源 - URL 缺 HTTPS 或末尾斜杠：
https://mirrors.aliyun.com/composer/✅，http://...❌，https://mirrors.aliyun.com/composer❌（无斜杠会导致路径拼接失败，部分版本返回 404）
验证是否生效：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或仍是 https://packagist.org，说明没写进去。
全局配置 vs 项目级配置：什么时候该用哪个
全局配置省事，但有隐藏风险；项目级更稳妥，尤其团队协作时：
立即学习“PHP免费学习笔记（深入）”；
- 全局配置（
composer config -g）改的是~/.config/composer/config.json，所有项目共享。适合个人开发，或团队初始化脚本中固化 - 项目级配置（去掉
-g，在项目根目录执行）会往composer.json的repositories字段里追加，只影响当前项目。如果已有私有源，命令会自动合并，不会覆盖 - 宝塔、Docker 或 CI 环境中要注意用户身份：宝塔默认以
www用户运行，而root下配的全局配置它读不到。得切到对应用户下配，比如sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
换镜像后还是卡？先看日志里卡在哪一步
加 -vvv 运行 composer install -vvv，盯紧输出关键词：
- 大量
GET https://mirrors.aliyun.com/composer/或Downloading xxx.zip→ 镜像已生效，下载环节正在加速 - 长时间停在
Resolving dependencies→ 和镜像无关，是本地 PHP 内存不足、启用了xdebug、composer.json里版本约束太宽（比如"*"）、或config.platform设置异常 - 若仍出现
could not find package，先执行composer clear-cache，再删掉vendor/和composer.lock，重新composer install
Docker 或 CI 环境中镜像配置容易漏掉的点
很多人在 Dockerfile 里只写了 RUN composer config -g repo.packagist ...，但构建阶段用的是 composer:latest 镜像，运行阶段切换成 php:8.2-fpm-alpine 后，这个配置就丢了——因为 composer 是独立容器，它的配置不会自动同步到 PHP 容器里。
- 正确做法是在 PHP 运行阶段镜像中重新配置，例如：
RUN composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 或者更彻底：在 PHP 容器启动前，把配置写进
/root/.composer/config.json（对应root用户）或/var/www/.composer/config.json（对应www-data用户） - 多阶段构建中，若用
COPY --from=composer /app/vendor /var/www/html/vendor，确保构建阶段也用了镜像源，否则vendor里的包还是从国外拉的
真正关键的不是选哪家镜像，而是确保 repo.packagist 这个键被正确写入、且不被项目级 repositories 覆盖——很多“配了没用”的问题，其实根本没走到镜像请求那一步。
