composer不支持多镜像自动fallback，必须通过脚本探测、切换配置、清缓存三步实现容灾；全局镜像仅能设一个repo.packagist单值，项目级repositories为顺序合并非fallback，插件方案仅解决下载阶段失败。
Composer 本身不支持多镜像自动 fallback，所谓“主备”“备用源”必须靠外部控制流实现——不是配几个 URL 就能切换，而是得用脚本探测、写入、清缓存三步闭环。硬塞多个 repositories 进 composer.json 不仅无效，还会让元数据混乱、安装变慢甚至失败。
为什么 composer config -g repo.packagist 只能设一个地址
repo.packagist 是 Composer 内部硬编码的单值字段，不是数组。你执行两次 composer config -g repo.packagist composer https://xxx，后一次会直接覆盖前一次，不会叠加。漏掉 composer 这个 type 值、URL 少斜杠、用 HTTP 而非 HTTPS，都会导致静默回退到 https://packagist.org，且不报错。
- 必须带
-g：否则只改当前项目，换目录就失效 - 键名只能是
repo.packagist（单数，不是repos.packagist或packagist.org） -
composer是必需的type值，不能省略或替换成其他字符串 - URL 必须是
https://mirrors.aliyun.com/composer/这种带末尾斜杠的 HTTPS 地址
项目级 repositories 数组不是 fallback，是顺序匹配
在 composer.json 里写多个 repositories，Composer 会按数组顺序请求每个源的 packages.json，合并成一张索引表；但下载时只从第一个声明了该包完整版本信息的源拉 ZIP，其余源完全不参与。超时、502、DNS 失败等网络错误直接中断，不会尝试下一个源——只有 404 才往下试。
- 一旦写了
repositories，全局配置（~/.composer/config.json）就完全失效，不是合并 - 想让官方源当兜底，必须显式加
{"type":"composer","url":"https://packagist.org"}到数组末尾，并确保"packagist.org": true或删掉该开关 - 私有源和镜像混写时，若私有源返回 404 而阿里云镜像返回 200，官方包仍走私有源路径（因元数据合并顺序导致 dist URL 被覆盖）
真·容灾：用脚本探测 + 切换 + 清缓存
CI/CD 或团队开发中防止单点失效，得自己控制流程。核心逻辑是三步：探测镜像根路径是否可访问 → 切换生效源 → 清缓存避免旧元数据干扰。下面这个 ~/bin/composer-safe-install 脚本可直接用：
#!/bin/bash
MIRROR_ALIYUN="https://mirrors.aliyun.com/composer/"
MIRROR_TENCENT="https://mirrors.cloud.tencent.com/composer/"
FALLBACK="https://repo.packagist.org/"
if curl -I -s -o /dev/null -w "%{http_code}" "$MIRROR_ALIYUN"packages.json | grep -q "200"; then
composer config -g repos.packagist "$MIRROR_ALIYUN"
elif curl -I -s -o /dev/null -w "%{http_code}" "$MIRROR_TENCENT"packages.json | grep -q "200"; then
composer config -g repos.packagist "$MIRROR_TENCENT"
else
composer config -g repos.packagist "$FALLBACK"
fi
composer clear-cache
composer install --no-interaction
- 脚本里用
curl -I检查packages.json是否返回 200，比单纯 ping 更准 -
composer config -g repos.packagist这里写的是repos.packagist（复数），但实际应为repo.packagist—— 注意修正，否则写不进有效字段 - 每次切换后必须执行
composer clear-cache，否则 Composer 仍读旧缓存 - 项目级切换要用
composer config repo.packagist ...（不加-g），并确保不覆盖已有私有源结构
插件方案：composer-plugin-mirror 是目前最轻量的选择
它能在下载失败时，按顺序尝试配置里的镜像地址，直到成功或全部失败，兼容 Composer 2/3，无需改源码。但要注意配置细节：
- 安装：
composer global require yunwuxin/composer-plugin-mirror - 配置镜像列表时，键名按字母序排序，所以用
mirror1、mirror2控制优先级 - 每个镜像都必须声明
packages，填["*"]表示承接全部包，否则只代理指定包名 - 命令示例：
composer config -g repositories.mirror1.type composer、composer config -g repositories.mirror1.url https://mirrors.tencent.com/composer/、composer config -g repositories.mirror1.packages '["*"]'
复杂点在于：插件只管下载阶段 fallback，不解决元数据拉取失败的问题；如果第一个镜像连 packages.json 都拿不到，它不会切，而是直接报错——这恰恰是多数卡顿发生的环节。所以探测脚本仍是更底层、更可控的选择。
