优先配置全局镜像源：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，确保所有命令（包括 docker 容器内、ci/cd）均生效，而非仅修改项目 composer.json；镜像同步有延迟，新包需等待 5–30 分钟，可 curl 检查镜像是否存在对应包。
composer install 时卡在 fetching packages 怎么办
国内直连 Packagist 官方源经常超时或 404，本质是 DNS 污染 + 连接重置导致的 composer install 卡死或报 Connection refused。不是网络差，是请求被中间设备拦截了。
- 优先改用国内镜像，不是“加个配置”就行，要确保所有流量走镜像——包括
packagist.org域名解析、https SNI、以及 Composer 的元数据接口（/packages.json等） -
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/是最简生效方式，它会写入全局auth.json同级的config.json，覆盖默认源 - 别手动改
composer.json里的repositories：那只能影响当前项目，且容易和minimum-stability冲突；全局配置才真正接管所有命令（create-project、require都生效） - 如果用了 laravel Sail / Docker，镜像配置必须写进容器内的
~/.composer/config.json，宿主机配了没用
fallback 镜像根本不存在，composer failover 是假概念
Composer 官方没有 failover、fallback 或多源自动切换机制。所谓“备用镜像”是社区误传——composer 不支持主备自动兜底，也不会在阿里云镜像失败后悄悄切到腾讯云。
- 你看到的“failover 教程”，实际是用 shell 脚本包装
composer install，捕获exit code 1后手动换源再试一次，属于外部重试，不是 Composer 自身能力 -
repositories数组里写多个源？没用。Composer 只认第一个 type=“composer” 的源，其余直接忽略（文档明确写 “only the first is used”） - 真要容灾，得靠 DNS 层（如自建 dnsmasq 把
packagist.org解析到不同镜像 IP）或 HTTP 层（nginx 反向代理 + upstream health_check），不是 Composer 配置能解决的
为什么换了镜像还是报 Package not found
镜像同步有延迟，尤其新发布的包或 dev 分支版本，阿里云/腾讯云镜像通常比官方晚 5–30 分钟。这不是配置错，是时间差。
- 先查包是否真在镜像中：
curl -I https://mirrors.aliyun.com/composer/p2/vimeo/vimeo-api.json，看返回 200 还是 404 - 确认你 require 的版本约束是否匹配镜像已同步的版本，比如
"vimeo/vimeo-api": "^4.0"可能还没同步，但"^3.0"已存在 - 私有包（如 gitlab 私仓）不受镜像影响，必须单独配置
repositories，且注意type: "vcs"和认证方式（auth.json里加 Token） - 运行
composer clear-cache再试，旧缓存可能记着官方源的 404 响应
CI/CD 中镜像配置最容易漏的点
github Actions、GitLab CI 默认不继承你的本地 Composer 配置，每次都是干净环境，不显式配置就直连官方源。
- GitHub Actions 必须在
steps里加run: composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，不能只靠cache步骤带配置 - GitLab CI 如果用了
composer:latest镜像，它自带的是官方源，必须在before_script里覆盖 - 缓存路径要一致：
~/.composer/cache是默认路径，如果 CI 脚本里用了--cache-dir自定义路径，镜像配置也得对应上，否则缓存不命中
换源本身很简单，麻烦的是边界情况：Docker 容器里没配、CI 每次重装、私有包和公开包混用、缓存与镜像不同步。这些地方一漏，就会回到“卡住”或“包找不到”的状态。