Composer中文镜像源宕机应急容灾方案

许多开发者都曾遇到过这样的困境：Composer 镜像一旦宕机，composer install 便会立即报错中断，没有任何自动切换机制。这并非程序缺陷，而是 Composer 的设计理念——它将 repositories 数组视为元数据合并表，而非请求路由表。当第一个镜像（例如阿里云）出现超时、502 或 DNS 解析失败时，安装流程会立刻终止，不会尝试后续备用源。因此，网上流传的“配置多个镜像源即可实现容灾”的说法，实际上是一个常见的误解。

镜像宕机时 composer install 直接报错，并非 Bug 而是设计策略

Composer 的容错策略实际上相当“僵化”：它将 repositories 数组作为元数据合并表处理，而非请求路由表。当首位镜像（如阿里云）返回超时、502 或 DNS 错误时，composer install 会立即中断，不会轮询后续镜像源。因此，多数开发者误以为配置多个源即可实现容灾，这其实是一种常见的认知偏差。

真正的容灾方案需要三步原子操作：探测、切换与清缓存

单纯依靠手动修改配置或等待重试并不能解决问题，必须通过脚本将以下三个步骤串联执行，缺一不可：

• 通过 curl -I -s -o /dev/null -w "%{http_code}" https://mirrors.aliyun.com/composer/packages.json 检测镜像根路径的 HTTP 状态码，若返回非 200 则判定镜像源不可用
• 执行 composer config repositories.packagist composer https://mirrors.tencent.com/composer/（仅项目级别，不加 -g 参数），动态切换至备用镜像源
• 务必执行 rm -rf ~/.composer/cache/repo/https---mirrors.aliyun.com-composer 删除缓存，因为 composer clear-cache 仅清除 ZIP 包，无法清除元数据缓存目录

切换镜像源后签名验证可能失效，安全风险常被忽视

直接使用 composer config -g repo.packagist composer https://xxx/ 会跳过签名校验，如果镜像缓存被污染或未同步 signature 字段，就可能拉取到已被篡改的包。正确做法如下：

• 开启签名验证功能：composer config -g security.signature true
• 使用正确的键名 repos.packagist（而非 repo.packagist），并将类型设为 composer：composer config -g repos.packagist.type composer
• 接着设置镜像 URL：composer config -g repos.packagist.url https://mirrors.aliyun.com/composer/
• 最后通过 composer diagnose 验证，输出中必须同时包含 secure-http: OK 和 signature verification: OK 两项

最可靠的保底方案是离线 install，而非依赖镜像切换

只要 composer.lock 文件存在且完整，composer install 完全可以不依赖网络请求——它仅从 ~/.composer/cache/files/ 读取 ZIP 包、校验哈希并解压。这才是镜像宕机时真正可靠的路径：

• 确保 composer.lock 文件被纳入 Git 版本控制，切勿将其列入 .gitignore
• 在 CI 流水线中配置复用 ~/.composer/cache 目录（例如使用 GitHub Actions 的 actions/cache 功能）
• 本地开发只需完成一次 composer install，缓存目录便会保存全部依赖；当镜像再次宕机时，执行 rm -rf vendor && composer install 依然可以成功安装

镜像配置仅用于加速，并非容灾的核心手段。许多开发者配置了阿里云镜像后便以为高枕无忧，却忽略了开启签名验证、固化 lock 文件、以及在 CI 中复用缓存等关键步骤——一旦镜像出现延迟，构建过程依然会失败。