Canonical 是 Composer 2.x 默认启用的仓库搜索机制，即命中首个匹配包后立即终止搜索；它通过加载顺序保障私有包不被公共同名高版本覆盖，生产环境应禁用 canonical:false 并使用数组声明仓库以确保顺序。
canonical 是 Composer 2.x 的默认仓库行为，它意味着“一旦在某个仓库中找到包，就立即停止搜索其他仓库”。这不是可选开关，而是底层解析逻辑的根本改变——你不需要手动开启，只要用的是 Composer 2.x，它就在生效。
为什么 canonical 会直接影响依赖安装结果？
关键在于「搜索终止时机」。比如你配置了两个仓库：
- 私有仓库 A（含
foo/barv2.1） - 公共 Packagist（含
foo/barv2.999）
在 Composer 1.x（非规范模式）下，即使 A 里已有 v2.1，Composer 仍会继续查 Packagist，并可能选中更高但不可信的 v2.999；而 2.x 下，只要 A 被排在前面且命中，v2.999 就根本不会被考虑。
这直接解决了「私有包被公共同名高版本覆盖」这类线上事故——不是靠运气或版本约束，而是靠加载顺序 + canonical 机制双重保障。
什么时候需要显式设 "canonical": false？
极少数场景：你想让某个镜像只做「补漏」，不参与主版本决策。例如：
{
"repositories": [
{
"type": "composer",
"url": "https://packages.example.com",
"canonical": false
}
]
}
此时即使该仓库提供了 monolog/monolog，Composer 也会继续往下找，只为确认有没有更新、更匹配的版本。但注意：
- 它破坏一致性：同一
composer install在不同仓库顺序下可能装出不同版本 - 拖慢安装：每个包都要遍历全部非规范仓库
- 通常只用于临时调试或灰度镜像，生产环境应避免
only 和 exclude 过滤比 canonical 更早生效
过滤规则在「是否进入该仓库搜索」阶段就起作用，比 canonical 判定还前置。例如：
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer",
"only": ["laravel/*"]
}
]
}
这个阿里云镜像只负责 laravel/* 包，其他所有包（比如 guzzlehttp/guzzle）压根不会去它那儿查——哪怕你把它放在第一个，也跳过。
这种组合很实用：把全量镜像设为 "canonical": false + "only" 白名单，既能保速度，又能防污染。
最容易被忽略的坑：对象写法 {"repositories": {"name": {...}}} 会破坏顺序
很多人图省事用对象方式写多个仓库，但 JSON 对象无序，composer.json 里的键顺序不保证执行顺序。结果就是：canonical 行为失效，私有仓库可能被 packagist 抢先命中。
务必用数组写法：
"repositories": [
{"type": "composer", "url": "https://private.example.com"},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer"}
]
顺序即策略。多一个逗号，少一次线上回滚。
