Composer 2.x新特性解析：Canonical Repositories（规范仓库）是什么？

Canonical 是 composer 2.x 默认启用的仓库搜索机制，即命中首个匹配包后立即终止搜索；它通过加载顺序保障私有包不被公共同名高版本覆盖，生产环境应禁用 canonical:false 并使用数组声明仓库以确保顺序。

canonical 是 Composer 2.x 的默认仓库行为，它意味着“一旦在某个仓库中找到包，就立即停止搜索其他仓库”。这不是可选开关，而是底层解析逻辑的根本改变——你不需要手动开启，只要用的是 Composer 2.x，它就在生效。

为什么 canonical 会直接影响依赖安装结果？

关键在于「搜索终止时机」。比如你配置了两个仓库：

• 私有仓库 A（含 foo/bar v2.1）
• 公共 Packagist（含 foo/bar v2.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"} ]

顺序即策略。多一个逗号，少一次线上回滚。