如何为Composer配置多个私有仓库并设置优先级？ (repository排序)

私有仓库配置必须用 repositories 索引数组，顺序即优先级；composer 按从上到下线性查找，首个匹配包即采用，不 fallback；禁用 packagist.org 后需显式添加；type 选 composer/vcs/package 影响解析逻辑。

私有仓库配置必须用 repositories 数组，顺序即优先级

Composer 解析依赖时，会按 repositories 数组从上到下的顺序依次查找包。第一个匹配到的版本即被采用，后续仓库即使有同名包也不会被检查。这不是“合并”，而是“短路查找”。

常见错误是把多个私有仓库写成对象（键值对），导致只有最后一个生效——repositories 必须是索引数组，且每个元素是带 type 和 url 的对象。

• 正确写法：

  {     "repositories": [         {             "type": "composer",             "url": "https://repo-a.example.com"         },         {             "type": "composer",             "url": "https://repo-b.example.com"         }     ] }

• 错误写法（会被覆盖）：

  "repositories": {     "a": { "type": "composer", "url": "https://repo-a.example.com" },     "b": { "type": "composer", "url": "https://repo-b.example.com" } }

• 若某仓库不可达或返回 404，Composer 不会自动 fallback 到下一个；它只在当前仓库中查不到包时才继续下一轮

混用 packagist.org 和私有仓库要显式声明 packagist.org

一旦定义了 repositories 数组，Composer 默认**禁用官方 Packagist**（即隐式设置 "packagist.org": false）。若你还想使用公共包（如 monolog/monolog），必须手动把官方源加回来，并控制其位置——放最后，确保私有包优先。

• 推荐结构：私有仓库靠前，packagist.org 显式置底

• {     "repositories": [         {             "type": "composer",             "url": "https://my-internal-repo.example.com"         },         {             "type": "composer",             "url": "https://partner-repo.example.com"         },         {             "packagist.org": true         }     ] }

• 不加最后一项会导致 composer require monolog/monolog 报错：Could not find package monolog/monolog

私有仓库类型选择：composer vs vcs vs package

不同场景对应不同 type，影响解析逻辑和优先级行为：

• "type": "composer"：适用于运行 Satis、private Packagist 或 Artifactory 的 Composer 服务端。支持完整元数据、版本发现和搜索，是多仓库协作的首选
• "type": "vcs"：直接指向 git/svn 仓库（如 "url": "https://gitlab.example.com/myorg/mylib.git"）。Composer 会克隆并读取 composer.json，但不支持版本列表缓存，每次 require 都可能触发远程探测，性能差且无法精确控制优先级（因版本号由 tag 决定，非仓库顺序）
• "type": "package"：手动内联一个包定义，适合极少数未托管在任何仓库的闭源组件。它绕过所有远程查找，但无法更新，维护成本高，慎用
• 混合使用时，vcs 和 package 类型仍受 repositories 数组顺序影响，但它们的“匹配逻辑”不同于 composer 源（例如 vcs 只在 URL 匹配且含有效 tag 时才参与解析）

验证优先级是否生效：用 composer show --all 和 composer why-not

光看 composer.json 顺序不够，得确认实际解析路径。两个命令最直接：

• composer show --all vendor/package-name：列出该包所有可用版本及来源（显示 “from repo-a.example.com” 这类提示），一眼看出 Composer 选了哪个仓库
• composer why-not vendor/package-name:1.2.3：如果某个版本没被装上，用它查“为什么不是这个版本”——常暴露因上游仓库没提供该版本，或被更早仓库的约束锁死
• 注意：运行前先 composer clear-cache，避免旧元数据干扰判断
• 调试时可临时加 -vvv，看到每一步尝试了哪些仓库（日志里会出现 Reading composer.json of https://...）

Composer 的仓库优先级本质是线性扫描，没有权重、没有分组、不支持条件路由。真正容易被忽略的是：一旦某个私有仓库返回了包的元数据（哪怕只是空列表或 404），Composer 就认为“已查过”，不会继续往下走——所以仓库 URL 的可用性和响应一致性，比排序本身更关键。