Composer 多镜像源按 repositories 数组顺序逐个尝试，首个匹配包的源即被采用，后续跳过；应将国内镜像置前、官方源 packagist.org 置后兜底，避免官方源前置导致镜像失效。
composer 配置多个镜像源时，repositories 顺序决定优先级
Composer 不支持“同时从多个源并行拉取”，它只按 repositories 数组里的顺序逐个尝试。第一个匹配到包的源就用它，后面的直接跳过。所以把国内镜像（比如阿里云、腾讯云）放在前面，官方源 packagist.org 放最后兜底，才是有效多源配置。
常见错误是把官方源写在最前，结果所有请求都走慢速通道，镜像形同虚设。
-
repositories是数组，必须保持索引顺序，不能靠type或url自动排序 - 自定义镜像（如私有 GitLab 包仓库）建议用
vcs类型，避免和composer类型镜像混淆 - 如果某个镜像临时不可用，Composer 会静默跳过，不会报错——这容易让人误以为“配置没生效”，其实是它已 fallback 到下一个
如何安全地添加阿里云 + 官方双源（不破坏现有项目）
直接改全局 config.json 风险高，推荐用项目级配置，且保留原始行为可逆性。
执行这条命令即可完成最小改动：
composer config repositories.packagist composer https://mirrors.aliyun.com/composer/
它会在 composer.json 的 repositories 下新增一个名为 packagist 的条目，并自动把原官方源设为 packagist.org 的 fallback（Composer 2.2+ 默认行为）。不需要手动删 packagist.org，也不用写完整 JSON 结构。
- 该命令等价于手动在
repositories里加一条：{"packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}} - 如果已有其他自定义源，注意别覆盖掉，可用
composer config --list检查当前配置 - 执行后运行
composer update -vvv，看日志里Downloading https://mirrors.aliyun.com/...是否出现，确认走的是镜像
私有包 + 公共镜像混用时，composer install 报 Could not find package xxx
这不是网络问题，而是 Composer 在解析依赖时，对每个包只查第一个能响应的源。如果你的私有包名和公共包名冲突（比如都叫 utils/helper），而私有源排在后面，就会漏掉。
- 私有源必须显式声明
packages列表或启用providersAPI，否则 Composer 不知道它能提供哪些包 - 把私有源放在
repositories数组最前面，确保优先匹配 - 避免给私有包起和 Packagist 上已存在包相同的名字，哪怕版本号不同——Composer 不按版本筛选源，只按包名路由
- 调试时加
-vvv参数，看日志里是否尝试访问你的私有源 URL；如果完全没出现，说明它被跳过了
镜像源切换后 composer update 仍很慢？检查 composer.lock 和缓存
Composer 会优先复用 composer.lock 里记录的下载 URL，而不是实时查 repositories。如果 lock 文件里还存着 packagist.org 的旧地址，即使你配了镜像，它也会先去官方源验证 hash，超时才 fallback。
- 运行
composer update --lock强制重写 lock 文件中的源地址（但不更新包版本） - 清空 Composer 缓存：
composer clear-cache，否则可能命中本地缓存的旧包元数据 - 某些公司代理或防火墙会拦截
HEAD请求，导致 Composer 误判镜像不可用而跳过——可临时加--no-cache测试是否为缓存干扰
