Composer仓库配置中仓库优先级深度解析-composer-PHP中文网

必须将私有仓库或国内镜像置于repositories数组首位，并在末尾显式添加{"packagist.org": false}，否则同名包会被packagist.org覆盖；composer按数组顺序线性匹配，首个返回200且含有效json的源即锁定使用，后续全跳过。

composer仓库配置中仓库优先级深度解析

要让Composer只从你指定的私有仓库或国内镜像安装包，而不是意外拉取packagist.org上的同名包，必须精确控制repositories数组中每个源的声明顺序和类型属性，否则同名包会被错误覆盖、版本劫持或镜像完全失效。

仓库优先级的本质是线性短路匹配

Composer不合并多个仓库的结果，也不做加权或并行查询——它严格按repositories数组从上到下发起HTTP请求，【第一个返回HTTP 200且响应体含有效JSON元数据的仓库，立即锁定使用，后续所有仓库彻底跳过】。

这意味：如果阿里云镜像对某个新包返回404，Composer不会自动切到腾讯云镜像，而是直接 fallback 到隐式 packagist.org（除非你显式禁用）；但如果它返回502或超时，Composer直接报错退出，连第二个源都不会试。

验证当前真实生效顺序：运行composer config repositories，输出结果就是实际匹配路径，别信注释或记忆。

私有仓库必须置顶且类型正确

方法一：VCS型私有包（如GitLab内部库）

第一步：在repositories数组最开头添加一项，type必须为"vcs"，url填完整Git地址（如https://gitlab.example.com/my-team/utils）。

第二步：确保该仓库对应分支已打Git tag（如v1.2.0），否则你在composer.json里写的"my-team/utils": "1.2.0"会失效——Composer找不到tag，只能退化为安装最新commit哈希，lock文件里变成"reference": "a1b2c3d"，不可复现。

方法二：Composer型私有仓库（如Satis或Private Packagist）

必须把type设为"composer"，且仍放在数组首位；若放错位置，同名包将被下方镜像或官方源抢先命中，私有逻辑彻底丢失。

国内镜像生效的唯一正确写法

镜像不是改个URL就行。必须显式声明"type": "packagist"，否则Composer把它当普通composer仓库处理，无法支持包名模糊搜索、自动补全等关键能力，还可能漏包。

正确结构示例：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

{

"repositories": [

{"type":"vcs","url":"https://gitlab.example.com/internal/sdk"},

{"type":"packagist","url":"https://mirrors.aliyun.com/composer/"},

{"packagist.org": false}

]}

【{"packagist.org": false}必须是独立对象，放在数组末尾，键名必须精确为packagist.org（不能是packagist或packagist.com）】。缺了这一项，哪怕镜像排第一，只要它对某包返回404，Composer立刻切回官方源，看起来像“镜像没起作用”。

删掉vendor和composer.lock再执行composer install，否则旧锁文件会固化错误源路径。