Composer仓库优先级由repositories数组顺序决定，但仅影响元数据合并；要强制走私有源，须禁用packagist.org、将私有源置顶，并确保其packages.json结构合法且包含完整包信息。
Composer 默认只用 packagist.org，要支持多仓库并控制优先级，核心是修改 repositories 数组顺序 + 合理设置 type 和 packagist 开关。
为什么改了 repositories 顺序还是没走私有源？
Composer 的仓库匹配逻辑不是“逐个尝试”，而是先查所有仓库的 composer.json 元数据（即 packages.json），再按 repositories 数组**从上到下**合并包信息；但真正下载时，它只认第一个能提供该包完整版本信息的仓库——也就是说，顺序只影响元数据合并阶段，不等于“请求转发顺序”。
- 如果你在顶部加了一个私有仓库，但该仓库的
packages.json里根本没声明monolog/monolog，Composer 就会继续往下找，最终从 packagist.org 拿元数据，然后仍从 packagist.org 下载 - 私有仓库必须包含完整、准确的
packages.json（含dist和source字段），否则无法接管下载 - packagist.org 是隐式存在的，除非显式禁用：
{"packagist.org": false}
如何强制 Composer 优先走私有源？
关键动作是：禁用默认 packagist，把私有源放在 repositories 第一位，并确保其能响应所有包的元数据请求（哪怕只是返回 404 或空列表）。
{
"repositories": [
{
"type": "composer",
"url": "https://your-private-repo.com"
},
{
"packagist.org": false
}
]
}
-
"type": "composer"表示这是一个标准 Composer 仓库（支持packages.json接口） -
{"packagist.org": false}必须作为独立对象写在数组里，不能合并进前一个对象 - 私有源 URL 必须可访问，且返回符合 Composer 协议的 JSON（如
/packages.json路径需返回顶层{"packages": {...}}） - 若私有源只托管部分包，其余包想 fallback 到 packagist，就不能关掉
packagist.org，而应使用repo.packagist.org显式声明，并放末尾
多个私有源共存时怎么控制优先级？
Composer 不支持 per-package 指定仓库，只支持全局合并。所以多个私有源共存时，优先级完全由 repositories 数组索引决定：越靠前，其 packages 数据越“权重高”；同名包的版本信息会被前面的覆盖后面的。
- 例如 A 源声明了
foo/bar:1.0.0，B 源也声明了同名同版本，但 A 在 B 前面 → Composer 只认 A 的dist地址 - 如果 A 源没声明某个包，B 源有，则用 B 的元数据
- 不建议混用
type: "package"（单包定义）和type: "composer"（全量仓库），前者无法参与版本合并，仅用于兜底个别包
{
"repositories": [
{"type": "composer", "url": "https://a.example.com"},
{"type": "composer", "url": "https://b.example.com"},
{"type": "package", "package": {"name": "legacy/tool", "version": "dev-master", "dist": {"url": "https://files.example/legacy.zip"}}}
]
}
常见错误：配置后 composer update 报 404 或找不到包
绝大多数情况是私有源的 packages.json 结构不合法，或路径未正确暴露。
- 检查
https://your-private-repo.com/packages.json是否返回 200 + 合法 JSON，且顶层有"packages"键 - 确认私有源是否支持
dist类型（"type": "zip"或"type": "tar"），否则 Composer 会退回到source克隆，而你可能没配 Git 访问权限 - 运行
composer config -g repos查看全局配置是否意外覆盖了项目级repositories - 用
composer diagnose验证配置合法性，它会提示缺失的 required keys
真正难的不是写几行 JSON，而是让每个私有源的元数据服务稳定、完整、低延迟——一旦某个源响应慢或返回空包列表，Composer 就会卡住或降级失败。别只盯着 repositories 顺序，先盯死私有源的 packages.json 输出质量。
