repositories 声明顺序决定包查找优先级，Composer 从上到下匹配首个版本即停止；自定义源须置数组开头才能覆盖 packagist.org 同名包，且需显式声明所需源并配合 "packagist.org": false 禁用默认源。

repositories 的声明顺序决定优先级

Composer 会按 repositories 数组中定义的**从上到下顺序**依次查找包，遇到第一个匹配的版本就停止搜索。Packagist 官方源（packagist.org）默认在最后隐式追加，所以只要把自定义源写在 repositories 数组开头，就能覆盖同名包。

常见错误是把私有源放在数组末尾，或误以为设置 packagist.org 为 false 就能“禁用”它——其实那只是屏蔽了自动发现，不阻止 Composer 在最后 fallback 到它。

• 必须显式声明所有需要的源，包括你想保留的 Packagist（如果还要用其他包）
• 若完全不用 Packagist，设 "packagist.org": false 后，仍需手动添加其他必需的公开源（如 packagist.phpcomposer.com 镜像）
• 类型为 vcs 的仓库（如 GitHub）优先级高于 composer 类型的私有源，但都受数组顺序控制

如何正确覆盖 packagist.org 上的同名包

假设你要用自己 fork 的 monolog/monolog 替换官方版，且托管在 GitHub：

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/yourname/monolog"
        },
        {
            "packagist.org": false
        }
    ],
    "require": {
        "monolog/monolog": "^2.10"
    }
}

关键点：

• vcs 源必须指向包含 composer.json 的仓库根目录，且该文件里 name 必须严格等于 monolog/monolog
• "packagist.org": false 要作为独立对象放在数组里，不能合并进前面的源配置
• 执行 composer update monolog/monolog 后，Composer 会拉取你仓库中匹配 ^2.10 的最新 tag，而非 packagist.org 上的

使用 composer type 私有源时的陷阱

如果你用的是私有 Composer 仓库（如 Satis 或 Private Packagist），类型为 composer，容易忽略两点：

• 该源的 packages 列表必须已包含你要覆盖的包，且版本号与 require 中声明的兼容；Composer 不会动态扫描你源里的 Git 分支
• 私有源响应的 JSON 必须带正确的 dist 或 source 字段，否则安装时可能报 Could not fetch 或回退到 packagist.org
• 调试可用 composer show -a monolog/monolog 查看实际解析到的源地址和版本来源

为什么 require-dev 中的包没被覆盖？

因为 repositories 全局生效，但 require-dev 的包在 composer install --no-dev 时不会加载，而某些 CI 场景默认跳过 dev 包——结果看似“没覆盖”，其实是根本没装那个包。

验证方式：

• 运行 composer install --with-all-dependencies 确保 dev 包参与解析
• 检查 composer.lock 中对应包的 source 字段，确认 url 指向你的私有源而非 https://api.packagist.org
• 私有源未启用 HTTPS 或证书异常时，Composer 可能静默降级到 packagist.org，此时 composer diagnose 会提示安全警告