Composer仓库优先级严格按repositories数组从上到下顺序匹配，遇首个可用源即停止查找；私有仓库须置顶，镜像需以packagist类型声明并置于私有仓后、官方源前。
Composer 的仓库优先级由 repositories 数组顺序决定
Composer 不会“自动排序”或“智能选源”，它严格按 composer.json 中 repositories 数组的**从上到下顺序**匹配包。遇到第一个能提供该包的仓库，就停止查找——后面的仓库根本不会被检查。
这意味着：把私有包仓库（如私有 GitLab、Satis 或 Toran）放在数组最前面，才能确保你自己的 my-company/utils 不被 packagist.org 上同名但不同内容的包覆盖。
- 顺序错位是私有包安装失败或拉错版本的最常见原因
- 如果没声明
repositories，Composer 默认只用 packagist.org（即隐式{"type": "packagist", "url": "https://packagist.org"}） - 添加镜像（如阿里云）不是加一个新仓库类型，而是把 packagist 类型的
url换成镜像地址
怎么安全地叠加 packagist 镜像 + 私有仓库
不能直接把镜像写成独立仓库，否则会丢失 packagist 全量索引能力；也不能把私有仓库放后面，否则可能被公共包“劫持”。正确做法是：显式声明 packagist 类型仓库，并把镜像 URL 塞进去，再把它放在私有仓库之后（因为私有仓库要优先）、默认源之前（保证 fallback 有效）。
示例 composer.json 片段：
{
"repositories": [
{"type": "vcs", "url": "https://gitlab.example.com/my-company/utils"},
{"type": "packagist", "url": "https://mirrors.aliyun.com/composer/"},
{"type": "packagist", "url": "https://packagist.org/"}
]
}
- 第一项是私有 VCS 仓库，只服务你自己的包，必须最前
- 第二项是阿里云镜像，
type仍为packagist，只是换了url；它能提供完整索引，且比官方快 - 第三项是兜底的官方源，仅当镜像临时不可用时生效（注意：Composer 不会自动 failover，需手动
composer clear-cache并重试） - 不要用
composer config -g repos.packagist.url全局改，它会覆盖项目级配置，导致私有仓库失效
composer require 时为什么还是拉了 packagist 的包？
典型现象：你明明在 repositories 里加了私有仓库，运行 composer require my-company/utils 却报错说 “Package not found”，或者更隐蔽地——成功安装了，但装的是 packagist 上同名的另一个包。
- 检查是否漏写了
"type": "vcs"（GitLab/GitHub 私仓必须显式声明，不能靠 Composer 自动推断） - 确认私有仓库的
composer.json里name字段和require时写的完全一致（包括大小写、斜杠方向） - 执行
composer show -p查看当前实际生效的仓库列表和顺序，别信配置文件没刷新 - 私有仓库如果是 Git 类型，Composer 默认只读
master或main分支的composer.json；如果包定义在dev-feature分支，得用"version": "dev-feature"显式指定
镜像 URL 写错或不可达时 Composer 怎么反应
Composer 对仓库 URL 的容错极低：只要 HTTP 请求返回非 200（比如 404、503、超时），它就直接报错并中断整个 install/update 流程，不会跳过该仓库去试下一个。
- 错误信息通常是：
Could not fetch https://mirrors.xxx.com/composer/packages.json, please review your configured sources. - 哪怕你写了三个仓库，第二个挂了，第三个也永远不会被访问
- 解决办法只有两个：临时注释掉故障仓库，或换一个可用镜像 URL（比如从腾讯云切到华为云）
- 没有“健康检查”机制，也没有重试策略，这是设计使然，不是 bug
真正难处理的不是排序本身，而是当团队多人协作时，有人本地加了全局镜像，有人项目里又写了一次，还有人用了 composer config --global repo.packagist.allow_ssl_downgrade true 这类危险开关——这些混在一起，会让仓库行为变得不可预测。
