Composer repositories 按数组顺序查找，首个匹配包即被采用，后续源不生效；应使用 type: "package" 精确声明私有包，保留 packagist.org 为兜底，避免 vcs 类型导致意外覆盖。
Composer 的 repositories 不支持“多层级优先级”或“源搜索顺序”的显式配置——它只按数组顺序从上到下依次查找包，**第一个匹配的包即被采用，后续源完全不生效**。所谓“优先级”，本质就是 repositories 数组的书写顺序。
为什么 composer.json 里 repositories 的顺序就是搜索顺序
Composer 在解析依赖时，会遍历 repositories 数组（包括默认的 packagist.org），对每个源执行 composer show vendor/package 类似的元数据查询。一旦某个源返回了匹配的包版本（哪怕只是 name 和 version 匹配），Composer 就立即停止继续查下一个源，并锁定该源的完整 package info（含 dist、source 等）。
- 这意味着：把私有仓库写在
repositories数组最前面，就能“覆盖” Packagist 上同名包 - 也意味着：如果两个源都提供了
monolog/monolog:2.10.0，只有第一个会被用，第二个完全被忽略 - 不存在“fallback 到下一个源”的机制；也不支持为不同 vendor 设置不同源
如何安全实现“私有包优先 + 公共包回退”效果
核心策略是：**用 package 类型仓库精确声明私有包，其余全部交给 packagist.org（或自建 proxy）处理**。避免用 vcs 或 composer 类型仓库兜底所有包，否则极易因命名冲突导致意外覆盖。
- 私有包必须明确指定
type: "package"，并完整写出name、version、dist地址和autoload -
repositories中只放你真正需要 override 的那几个包，不要放整个私有仓库地址（如"type": "composer", "url": "https://repo.example.com"） - 保留
{"packagist.org": true}（或显式添加 packagist.org）作为最终兜底 - 若需统一代理公共包，应使用 Satis 或 Private Packagist，而非靠 Composer 自身排序模拟
{
"repositories": [
{
"type": "package",
"package": {
"name": "acme/internal-sdk",
"version": "1.5.0",
"dist": {
"url": "https://artifacts.example.com/acme/internal-sdk-1.5.0.zip",
"type": "zip"
},
"autoload": { "psr-4": { "Acme\\Sdk\\": "src/" } }
}
},
{
"packagist.org": true
}
],
"require": {
"acme/internal-sdk": "^1.5",
"monolog/monolog": "^2.10"
}
}
常见错误：vcs 仓库 + packagist 混用导致的意外覆盖
典型现象：项目中引入了 "type": "vcs" 指向 GitHub 私有库，结果发现 symfony/console 安装失败，或安装的不是预期版本。这是因为 Composer 会尝试在该 vcs 源中查找所有包（包括 symfony/console），而 GitHub 仓库显然没有这个包，触发 404 或空响应，最终中断解析流程。
-
vcs类型仓库仅适用于「你确定该 Git 仓库本身就是一个 Composer 包」的场景（如 fork 后打 patch） - 切勿用
vcs指向一个不含composer.json的仓库，或指向组织级 URL（如https://github.com/acme/） - 如果私有包托管在 GitLab/GitHub，且每个包独立仓库，请为每个包单独声明
package类型，而不是用vcs扫描整个域 - 运行
composer diagnose可检测出无效的vcs配置；加-vvv参数安装时能看到实际查询了哪些源
真正难的不是写对顺序，而是厘清“哪些包必须由谁提供”。一旦把 repositories 当作路由表来用，就容易陷入覆盖失控、版本漂移、CI 缓存污染等连锁问题。最稳的方式，永远是让每个包的来源在 composer.json 中显式、唯一、不可歧义地定义清楚。
