composer 2.2+ 支持全局 fallback 镜像源,执行 composer config -g repositories.packagist composer https://mirrors.aliyun.com/composer/ 和 composer config -g repositories.packagist.fallback true 即可启用,失败时自动回退至镜像源。

Composer 默认使用 packagist.org,国内访问慢或不稳定时,可以配置备用镜像源,让 Composer 在主源失败时自动回退到镜像源。
配置全局 fallback 镜像(推荐)
从 Composer 2.2 开始,支持通过 repositories 的 fallback 属性指定备用源。只需在全局配置中添加一个带 "fallback": true 的 packagist 镜像即可。
执行以下命令,添加阿里云镜像作为 fallback:
composer config -g repositories.packagist composer https://mirrors.aliyun.com/composer/
再启用 fallback 标志:
composer config -g repositories.packagist.fallback true
验证 fallback 是否生效
Composer 会优先尝试官方源,失败后才用镜像源。你可以临时断网或修改 hosts 屏蔽 packagist.org 来测试:
- 运行
composer show symfony/console,观察是否最终成功拉取 - 加
-v参数(如composer show -v symfony/console)可看到请求日志,确认是否切换到了镜像源
注意事项和常见问题
fallback 机制依赖 Composer 版本(≥2.2),旧版本不支持该特性。若你用的是 Composer 1.x,需手动切换镜像或升级。
- 不要同时启用多个
fallback: true的源,Composer 只认第一个标记为 fallback 的 packagist 类型仓库 - 镜像源地址必须是完整 URL,末尾斜杠不能省略(如
https://mirrors.aliyun.com/composer/) - 全局配置文件位置可通过
composer config -g --list查看,通常在~/.composer/config.json
基本上就这些。配置好后,Composer 会自动兜底,不用每次手动切源,也不影响包的完整性校验。