Composer按repositories数组顺序线性匹配，首个返回有效元数据的源即被采用，后续全跳过；私有仓须置首位并用对应type，镜像需显式声明"type":"packagist"且置于私有仓之后、默认源之前。
repositories数组顺序决定包来源，不是“多个源一起查”
Composer 不会合并或加权多个仓库的结果，它只按 repositories 数组从上到下逐个尝试，**第一个能提供目标包的仓库就立即采用，后面的全被跳过**。所谓“多渠道”，本质是线性 fallback 链，不是并行查询。
常见错误是把私有包仓库（如内部 GitLab 或 Satis）放在 repositories 数组末尾，结果同名包被 packagist.org 先命中，装了公共版本——这根本不是网络慢导致的“偶然拉错”，而是配置顺序写反了。
- 私有包必须声明为
"type": "vcs"或"type": "package"，且放在repositories第一位 - 若要用国内镜像加速，应显式声明一个
"type": "packagist"仓库，URL 换成https://mirrors.aliyun.com/composer/，并把它放在私有仓之后、默认源之前 - 绝对不要省略
repositories中的"type": "packagist"条目——否则 Composer 会退回到隐式官方源，绕过你的镜像
packagist 镜像必须显式声明 type，不能只改 URL
很多人以为在 composer.json 里把 "url": "https://packagist.org" 改成阿里云地址就行，其实不行。Composer 对 "type": "packagist" 有特殊处理逻辑：只有明确写了这个 type，它才会启用 packagist 协议的完整索引能力（比如支持模糊搜索、自动补全包名）。随便换个 URL 而不带 type，会被当成普通 "type": "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/my-company/utils"},
{"type": "packagist", "url": "https://mirrors.aliyun.com/composer/"},
{"type": "packagist", "url": "https://packagist.org"}
]
}
注意最后一条是兜底项，确保没被镜像覆盖的包仍可安装；但只要前两条能响应，它就永远不会被用到。
私有包没打 tag 就别指望版本号生效
如果你的私有仓库是 Git 类型（"type": "vcs"），而目标分支（如 main）没打任何 Git tag，Composer 默认会 fallback 到 commit hash 安装。这时你在 composer.json 里写的 "my-company/utils": "1.2.0" 根本不生效——因为 1.2.0 这个 tag 不存在，Composer 只能取最新 commit，并记进 composer.lock 为类似 "reference": "a1b2c3d..." 的哈希值。
- 强制要求所有私有包发布时打符合语义化版本的 Git tag（如
v1.2.0） - 如果暂时无法打 tag，可在
repositories中用"package"类型手动声明版本映射，但维护成本高 -
composer install时加--no-cache有助于暴露这类问题：缓存可能掩盖未打 tag 导致的版本漂移
conflict + require-dev 分离才是防劫持的双保险
仅靠仓库顺序和镜像配置，防不住开发人员手误执行 composer require 引入未经审核的包。真正锁死的关键是组合策略：
- 在
composer.json的"conflict"字段里明确禁止已知高风险或不合规的包，例如："conflict": {"laravel/tinker": "*"} -
require-dev里的工具类依赖（如phpunit/phpunit）必须和require分开管理——CI 流水线跑composer install --no-dev时，它们根本不该出现在生产vendor/里 - 检查
composer.lock是否含require-dev包的记录：如果有，说明有人在生产环境执行了--dev，这是权限或流程漏洞
仓库优先级解决“从哪拉”，conflict 和 require-dev 隔离解决“不该拉什么”。两者缺一不可，尤其在多人协作或接入外包团队时，后者比前者更难被绕过。
