Composer镜像配置失效主因是键名错（应为单数repo.packagist）、缺type值“composer”、URL末尾无/，三者任一出错均静默回退官方源，且需执行composer clear-cache并验证config输出是否为完整JSON。
不配中文镜像，Composer 在国内基本跑不起来——不是慢，是频繁卡在 Downloading、报 403、连不上 packagist.org，根本走不到安装逻辑。
composer config -g repo.packagist 命令为什么总不生效
90% 的“配了没用”问题，其实命令压根没写进去，而 Composer 2.2+ 会静默 fallback 回官方源，不报错也不提醒。关键就卡在三个硬性条件：
-
repo.packagist键名不能拼成repos.packagist（多一个s就失效） - 第二个参数必须是
composer，这是仓库类型声明，漏掉它会被当无效配置丢弃 - URL 必须以
https://开头，且末尾带/：比如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌
验证是否真正生效，只看这一行输出：composer config -g repo.packagist
正确结果必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，或者新版直接输出 URL 字符串。空、null、或还是 https://packagist.org，说明没写成功。
宝塔 / CI / Docker 环境里镜像为啥不起作用
全局配置写在当前用户的 ~/.config/composer/config.json（Linux/macOS）或 %USERPROFILE%\AppData\Roaming\Composer\config.json（Windows），但它只对那个用户生效。宝塔的 PHP 进程、CI 的 runner、Docker 容器里的脚本，往往不是你登录时的用户。
- 宝塔默认以
www用户运行，得切过去配：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - GitHub Actions 或 GitLab CI 推荐项目级配置，避免依赖宿主用户环境
- Docker 构建中，如果用
root用户构建但最终容器以非 root 运行，全局配置也读不到
更稳妥的做法：进项目根目录，执行不带 -g 的命令，让镜像写进 composer.json 的 repositories 字段里，这样所有环境都认。
立即学习“PHP免费学习笔记（深入）”；
项目已有私有仓库，怎么加镜像还不破坏原有配置
别手动编辑 composer.json，容易引号错位、括号不全、格式损坏。用 Composer 自带合并机制最安全：
- 确保
composer.json中已存在"repositories": []或"repositories": {}字段 - 在项目根目录运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意没-g） - 它会自动向数组追加新项，或把空对象转为标准数组并插入，不会覆盖已有的 Git 私有源
- 切记顶层不要加
"packagist": false——这会让php、ext-json等基础包校验失败
改完建议删掉 vendor/ 和 composer.lock，再跑一次 composer install，否则旧 lock 文件可能仍指向 packagist.org 的 hash，导致安装失败或版本不一致。
最常被忽略的一点：镜像配置只是第一步，composer clear-cache 必须跟上。缓存里还存着旧源的 packages.json，不清理，新配置在首次 install 时照样走不通。
