Composer仓库优先级由配置顺序与"packagist": false开关共同决定：未禁用时官方源兜底，顺序无关；禁用后严格按repositories数组从上到下匹配，首个返回元数据的仓库生效。

composer config 的 repo 优先级规则

Composer 的仓库优先级不是靠“排序”决定的，而是按「配置顺序 + 类型匹配」动态生效。你写在 composer.json 里的 repositories 数组，从上到下依次尝试匹配包名；但一旦某个仓库声明了 "packagist": false，Packagist 官方源就完全被禁用——此时顺序才真正起作用。

• 没禁用 Packagist 时：repositories 仅用于补充（比如私有包），官方源始终兜底，顺序无关紧要
• 禁用了 Packagist（"packagist": false）后：Composer 严格按数组索引顺序查找，第一个能返回该包元数据的仓库胜出
• 多个仓库都声明了同一包（如 monolog/monolog），且都返回了版本信息，Composer 不合并，只取第一个匹配仓库的结果

如何强制让私有源优先于 packagist.org

必须显式关闭默认源，并把私有仓库放在 repositories 数组最前面。否则 Composer 会先去 packagist.org 查，即使你的私有源有同名包也根本不会触发。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 在 composer.json 中添加：

  "repositories": [
    {
      "type": "composer",
      "url": "https://your-private-repo.com"
    },
    {
      "packagist": false
    }
  ]

• 注意顺序不能颠倒：{"packagist": false} 必须在私有源之后（它是“开关”，不是仓库本身）
• 运行 composer config -g repos.packagist false 是全局禁用，不推荐——它会影响所有项目，且无法指定私有源

常见错误：镜像源 + 私有源混配失败

国内镜像（如阿里云、腾讯云）本质是 packagist.org 的只读代理，它们不支持托管私有包。如果你把镜像写在 repositories 里，又同时加了私有源，但没关 packagist，Composer 仍可能绕过私有源直连镜像查公开包——而镜像根本没有你的私有包，结果报 Could not find package xxx。

• 验证是否生效：运行 composer config repositories，确认输出中包含你的私有源 URL，且 packagist 显示为 false
• 调试技巧：加 -vvv 参数执行 composer require，看日志里实际请求了哪个源的 packages.json
• 别用 composer config --global repo.packagist composer https://mirrors.aliyun.com/composer/ 这种写法——它会覆盖掉整个 packagist 配置，导致私有源失效

require 时包名冲突的真实表现

当两个仓库都提供同名包（例如 foo/bar），且你禁用了 packagist，Composer 只认第一个仓库返回的版本列表。哪怕第二个仓库有更新的 dev-main，只要第一个仓库没声明，composer require foo/bar:dev-main 就会失败。

• 检查冲突：用 composer show foo/bar --all 看实际加载的是哪个源的版本
• 临时覆盖：可通过 composer require foo/bar:dev-main --repository-url=https://your-private-repo.com 强制指定源
• 长期方案：确保私有源的 composer.json 中 name 字段唯一，或用 replaces 字段声明替代关系，避免同名包共存

Composer 的仓库优先级不靠拖拽排序，靠配置顺序和 packagist 开关的组合生效。最容易漏掉的是那个 {"packagist": false} ——少了它，前面写的私有源等于白配。