Composer仓库优先级取决于包名是否匹配，而非数组顺序；只有声明支持目标包的仓库才会被查询，需用package类型或显式配置确保指定源下载。
Composer 默认只从 Packagist 官方源下载包，但你加了 repositories 后，它不会“自动按顺序试”，而是根据包名是否匹配来决定是否查某个源——匹配就查，不匹配就跳过。所谓“优先级”，本质是「包名命中规则的先后判断逻辑」，不是网络请求的排队顺序。
为什么 repositories 数组顺序不等于下载优先级
Composer 会遍历 repositories 列表，对每个仓库检查：该仓库是否声明支持你要安装的包（通过 packages、pattern 或完整包名白名单）。只有明确声明支持的仓库才会被查询。数组靠前 ≠ 优先下载，除非它明确覆盖了目标包。
常见误解场景：
- 你把私有仓库放第一位，但没在
packages里列出myorg/utils→ Composer 仍会回退到 Packagist 查找 - 两个仓库都声明支持
monolog/monolog→ Composer 可能用后一个（取决于内部解析顺序），行为未定义，应避免
正确做法是：用 composer config repositories.0 显式控制单个包的来源，或用 package 类型仓库精准锁定。
如何强制某包走指定仓库（绕过 Packagist）
最可靠的方式是使用 package 类型仓库，完全接管某个包的元数据和下载地址。适用于私有包、fork 替换、或临时 patch 版本。
示例：强制 acme/logger 从 Git 仓库安装 v1.2.0：
{
"repositories": [
{
"type": "package",
"package": {
"name": "acme/logger",
"version": "1.2.0",
"dist": {
"url": "https://git.example.com/acme/logger/archive/v1.2.0.zip",
"type": "zip"
},
"autoload": {
"psr-4": {
"Acme\Logger\": "src/"
}
}
}
}
],
"require": {
"acme/logger": "1.2.0"
}
}
注意：package 类型仓库必须包含完整元信息（autoload、require 等），且 version 必须与 require 中一致，否则会报 Could not find package acme/logger。
私有 Git 仓库 + Packagist 混合使用的安全配置
若你有公司私有 GitLab/GitHub 仓库，并希望优先查私有源、缺失时再 fallback 到 Packagist，需两步操作：
- 将私有源设为
vcs类型，并确保其composer.json中name字段与你require的包名完全一致 - 禁用 Packagist 默认源（避免它抢答），再显式添加 Packagist 作为兜底
执行命令：
composer config --unset repositories.packagist composer config repositories.private-vcs vcs https://git.example.com/myorg/private-packages composer config repositories.packagist composer https://packagist.org
这样 Composer 会先查 private-vcs，找不到对应包时才查 packagist。关键点在于：Packagist 必须以 composer 类型显式添加，且不能保留默认隐式源（它优先级最高，会跳过你的自定义列表）。
调试仓库匹配过程：用 composer diagnose 和 -v
当包没走预期源时，别猜，直接看 Composer 实际做了什么：
-
composer diagnose会提示仓库配置是否合法、是否有重复包名 -
composer require vendor/package -v显示每一步查了哪些仓库、是否命中、是否跳过 - 重点观察日志中类似
Skipping repository ... because it does not contain vendor/package的行
如果你看到「Skipping」却期望它不跳过，说明该仓库的 composer.json 缺少 "name": "vendor/package"，或你在 repositories 中用了 package 类型但没写全字段——这是最常被忽略的细节。
