Composer 的 repo.packagist 不支持多个 URL，因其底层仅接受单个仓库地址；多镜像高可用需借助插件（如 composer-plugin-mirror）或 shell 脚本实现自动 fallback。
为什么 composer config repo.packagist 不能直接填多个 URL
因为 Packagist 官方协议只允许一个主仓库地址，Composer 的 repo.packagist 配置项底层对应的是单个 composer.json 中的 repositories 第一项（即 packagist.org 的替代），它不支持数组或 fallback 列表。你硬塞多个 URL 进去，Composer 会报错：Invalid repository type "package" 或直接忽略后续地址。
真正能“多镜像”的路径只有一条：用自定义仓库 + 镜像代理逻辑，或者靠插件在运行时动态切换。
- 官方
repositories数组里可以加多个仓库，但 Composer 默认只查第一个（packagist类型），其余必须是明确包名前缀的package或vcs类型，无法兜底 -
composer config -g repos.packagist设置全局镜像，也只接受一个 URL - 所谓“多镜像高可用”，本质是「故障自动降级」，不是「同时请求多个」
用 composer-plugin-mirror 实现自动 fallback
这是目前最轻量、无需改源码、兼容 Composer 2/3 的方案。它会在安装失败时，按顺序尝试配置里的镜像地址，直到成功或全部失败。
执行以下命令安装插件：
composer global require hirak/prestissimo --no-plugins composer global require yunwuxin/composer-plugin-mirror
然后在全局配置中写入镜像列表（注意顺序：优先级从高到低）：
composer config -g repositories.packagist.type composer composer config -g repositories.packagist.url https://packagist.phpcomposer.com composer config -g repositories.packagist.packages '["*"]' composer config -g repositories.mirror1.type composer composer config -g repositories.mirror1.url https://packagist.laravel-china.com composer config -g repositories.mirror1.packages '["*"]' composer config -g repositories.mirror2.type composer composer config -g repositories.mirror2.url https://mirrors.aliyun.com/composer/ composer config -g repositories.mirror2.packages '["*"]'
- 插件会按
repositories键名排序（字母序），所以用mirror1、mirror2确保顺序可控 - 每个镜像都必须声明
packages，填["*"]表示承接全部包，否则只代理指定包名 - 首次请求走第一个镜像；若返回 404 或超时（默认 5 秒），自动切到下一个
- 不修改本地
composer.lock，不影响 CI/CD 环境一致性
手动 fallback：用 shell 脚本包装 composer install
如果你不能装全局插件（比如 CI 环境权限受限），就用脚本控制流程。核心思路是捕获错误码，重试不同 COMPOSER_REPO_PACKAGIST 环境变量。
示例脚本（保存为 safe-composer-install）：
#!/bin/sh MIRRORS='https://packagist.phpcomposer.com https://packagist.laravel-china.com https://mirrors.aliyun.com/composer/' for url in $MIRRORS; do echo "Trying mirror: $url" COMPOSER_REPO_PACKAGIST=$url composer install --no-interaction && exit 0 sleep 1 done echo "All mirrors failed." exit 1
- 必须用
COMPOSER_REPO_PACKAGIST（不是repo.packagist），这是 Composer 内置的环境变量开关 -
composer install成功时退出码为 0，失败一般为 1 或 2；脚本靠这个判断是否继续 - 不要加
--prefer-dist或--no-cache进去，它们和镜像切换无关，反而可能掩盖真实错误 - 某些私有镜像（如腾讯云）需要额外 header，这时得换
curl+composer create-project --repository-url组合
镜像地址失效后，composer update 卡住却不报错？
这是最常被忽略的坑：Composer 默认对远程仓库有强缓存（尤其是 packages.json 元数据），即使镜像挂了，它也可能读本地旧缓存，假装还在工作，实际卡在静默重试（最长可达 30 秒以上）。
- 先执行
composer clear-cache，再试；别信 “刚换的镜像应该生效了” - 加
-v参数看详细日志：composer update -v 2>&1 | grep -i 'fetching\|mirror'，确认实际请求的是哪个 URL - 某些镜像（如早期阿里云）不支持
/p/xxx.json路径，会返回 404，但 Composer 不立即失败，而是降级走packages.json全量拉取——这会导致巨慢且内存爆掉 - 验证镜像是否真可用，直接
curl -I https://mirrors.aliyun.com/composer/packages.json，看是否返回 200 + 正确Content-Type: application/json
镜像高可用不是配完就完事，关键在故障时能否秒级感知和切换。很多人卡在缓存没清、日志没开、URL 拼错这三步上，而不是技术本身有多难。
