Composer 多镜像不自动 failover 是因按序查找且超时等待30秒，需禁用默认源并显式声明阿里云与官方源顺序协作。
为什么 repositories 里配多个镜像不会自动 failover？
Composer 的 repositories 是静态声明式配置，不是负载均衡或故障转移列表。它按顺序查找包：先查第一个源，命中就用，不命中才查第二个——但「不命中」指该源明确返回「包不存在」（HTTP 404 或 Composer 的 repo.packagist.org 返回空响应），而不是连接超时或 500 错误。一旦某个源因网络问题卡住，Composer 默认会等满 30 秒才失败并尝试下一个，导致整体安装巨慢。
常见错误现象：composer install 卡在 Downloading https://packagist.org/packages.json 十几秒，其实是因为主源不可达，但 Composer 还没放弃。
- 必须显式禁用默认源（
"packagist.org": false），否则你配的镜像只是「额外源」，Composer 仍会优先走官方源 - 国内常用镜像（如阿里云、腾讯云、华为云）不完全同步 packagist 元数据，部分私有包或新发布包可能查不到，得保留一个兜底源（比如官方源本身）
- 不要把镜像地址写成
https://mirrors.aliyun.com/composer/—— 正确路径是https://mirrors.aliyun.com/composer/后面**不能加packages.json或其他后缀
怎么写 repositories 才让阿里云 + 官方源协同工作？
核心是关闭默认源，把镜像和官方源都列为显式仓库，并靠顺序控制优先级。以下是最简可用配置：
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"type": "composer",
"url": "https://packagist.org/"
}
],
"packagist.org": false
}
说明：
-
"packagist.org": false必须写在根节点，不是repositories里；漏掉这句，你的镜像只是「锦上添花」，不是「替代方案」 - 两个源都用
"type": "composer"，别写成artifact或package，否则无法查包列表 - 阿里云镜像响应快但偶尔滞后几小时，官方源永远最新但慢；把阿里云放前面，能覆盖 99% 场景，真遇到新包再 fallback 到官方源
- 如果项目依赖私有 Git 包（
"type": "vcs"），它们不受repositories顺序影响，仍走各自定义的 URL
composer config 命令能不能直接设多个镜像？
不能。运行 composer config repositories.0.url https://mirrors.aliyun.com/composer/ 只能覆盖第 0 个源，且会清空原有 repositories 数组。命令行方式只适合单镜像临时切换，不适合多源协作。
正确做法是直接编辑 composer.json，或者用脚本生成：
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ composer config -g repos.packagist-fallback composer https://packagist.org/
但注意：composer config -g 写的是全局配置（~/.composer/config.json），它和项目级 composer.json 的 repositories **不合并**，而是被后者完全覆盖。所以项目里必须自己写全。
- 全局配置只影响没有声明
repositories的项目，一旦项目写了，全局就失效 - CI 环境中，别依赖全局 config，所有镜像逻辑必须进项目
composer.json - 别用
composer config --unset repositories清空——它会删整个字段，导致找不到包
为什么有些包还是从 packagist.org 下载，哪怕镜像里有？
因为 Composer 缓存了元数据（packages.json）。即使你改了 repositories，旧缓存仍指向老地址。执行 composer clear-cache 后再 install，才能确保走新源。
更隐蔽的问题：某些镜像（如华为云）对带版本约束的包（如 "monolog/monolog": "^2.0"）返回的下载 URL 仍是 packagist.org 的 dist 链接，而非镜像自身域名。这是镜像服务端未重写 dist URL 导致的，客户端无法干预。
- 检查实际下载地址：运行
composer install -vvv，看日志里Downloading行的 URL - dist 文件（zip/tar）是否走镜像，取决于镜像服务商是否做了完整代理；阿里云和腾讯云基本做到了，华为云目前仍有部分未代理
- 如果你发现 dist 还是从官方下，但 metadata（packages.json）已从镜像读取，说明镜像服务本身有缺陷，换源或等修复
最麻烦的点其实是：镜像之间的元数据同步延迟、dist URL 重写不一致、以及 Composer 自身对错误源的等待策略——这些细节不报错，但会让构建变慢或偶发失败，得靠 -vvv 日志一点点核对。
