如何配置多个镜像源作为备选？（高可用配置）

Composer 配置多个镜像源时，repositories 顺序决定优先级

Composer 不支持“自动故障转移”或“轮询式”多镜像，它只按 repositories 数组顺序逐个尝试，第一个能连通且返回有效包信息的源即被采用。后续源完全不参与本次安装——哪怕第一个响应慢、第二个更快，也没用。

实操建议：

• 把最稳定、延迟最低的镜像（如阿里云 https://mirrors.aliyun.com/composer/）放在 repositories 数组首位
• 官方源 https://packagist.org 必须显式声明在最后，否则会被默认源覆盖，导致私有包或 fork 包无法加载
• 不要把多个国内镜像并列堆砌——它们地址不同但数据同步延迟一致，重复配置只会增加解析开销，不提升可用性

如何避免因镜像不可用导致 composer install 卡死或失败

默认情况下，Composer 遇到超时或 502/503 错误会重试多次再报错，用户感知是“卡住”。这不是配置问题，而是网络层行为。

实操建议：

• 加 --no-interaction 和 --prefer-dist 减少交互和源码拉取开销
• 设置超时：在 composer.json 中添加 "config": { "github-protocols": ["https"], "http-basic": {}, "fxp-asset": { "timeout": 10 } }（注意：fxp-asset 是旧插件配置，已废弃；真正有效的是全局配置 composer config --global repo.packagist.org.url https://mirrors.aliyun.com/composer/）
• 更可靠的做法是用环境变量临时切换：COMPOSER_REPO_PACKAGIST=https://mirrors.tuna.tsinghua.edu.cn/composer/ composer install

 composer.json 里写死多个 repositories 的典型错误

常见错误现象：执行 composer update 报错 Could not load package xxx in http://packagist.org，但该包明明在阿里云镜像里存在。

原因在于：你把自定义镜像写成了 type: "composer"，却没确保其 packages 接口返回结构与 packagist 兼容；或者用了 type: "package" 手动定义单个包，却漏写了 dist 或 source 字段，导致 Composer 无法下载。

实操建议：

• 国内镜像必须用 type: "composer"，且 URL 末尾带 /（如 "url": "https://mirrors.aliyun.com/composer/"）
• 不要混用 type: "composer" 和 type: "package" 在同一 repositories 列表里——Composer 会全部走第一种逻辑，后者被忽略
• 私有 Git 包请用 repositories + type: "vcs"，而非伪造一个镜像源

CI/CD 环境中实现镜像高可用的务实做法

本地开发可以手动切镜像，但 CI 流水线需要确定性。硬编码多个镜像进 composer.json 反而增加维护负担，也违背“环境隔离”原则。

实操建议：

• CI 脚本开头统一设置镜像：composer config --global repos.packagist composer https://mirrors.aliyun.com/composer/
• 加兜底逻辑：用 curl -I -s -f -m 5 https://mirrors.aliyun.com/composer/packages.json | grep "200 OK" || composer config --global repos.packagist composer https://packagist.org
• 避免在 composer.lock 提交中固化镜像 URL——它只记录包版本，不记录源地址；源地址由运行时环境决定

真正的高可用不在配置多几个 URL，而在让每次构建都能快速、确定地选中一个可用源。网络抖动时，靠重试和超时控制比靠堆镜像更可控。