canonical是Composer 2.x默认启用的仓库搜索机制，即命中首个匹配包后立即终止搜索；它通过仓库声明顺序保障私有包不被公共同名高版本覆盖，生产环境应禁用canonical:false并使用数组声明仓库以确保顺序。
non-canonical 仓库不是用来“优化加载顺序”的，而是让 Composer 继续搜索后续仓库——哪怕当前仓库已经找到了包。它解决的不是“谁先加载”，而是“要不要继续找更高版本”。直接设 "canonical": false 不会加速、也不会让私有包优先，反而可能破坏依赖确定性。
为什么你不需要 non-canonical 来“优先加载本地包”
私有包优先靠的是 repositories 数组顺序 + 显式禁用 packagist.org，不是靠关 canonical。canonical 控制的是“找到就停”，而你真正想控制的是“从哪开始找”。
-
"canonical": true（默认）：在第一个能提供myorg/utils的仓库命中后，立刻停止查找 —— 这正是你要的“私有包不被公共源覆盖” -
"canonical": false：即使私有仓库返回了myorg/utils ^1.2，Composer 还会继续查后面仓库，试图找^1.9或^2.0—— 这在生产环境是危险行为 - local path/vcs 仓库本身不参与“包列表扫描”，只在
require明确写死时才拉取，根本不受 canonical 影响
真正决定“本地包是否被优先加载”的三件事
顺序、类型、开关缺一不可。漏掉任意一项，composer require myorg/utils 就会 fallback 到 packagist.org。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 私有仓库必须是
"type": "composer"，不能是"type": "vcs"或"type": "package"—— 后两者不提供完整包索引，无法参与“按名匹配” - 必须把私有仓库放在
repositories数组最前面，且紧跟着写{"packagist.org": false}（注意：不是数组第一项，是最后一项） - 验证是否生效：运行
composer config repositories，输出里不能出现"packagist.org": true或缺失该键 - 如果私有仓库 URL 返回 401，记得提前配好
http-basic：composer config http-basic.packages.internal user pass
什么时候才该用 "canonical": false
仅限两类场景：VCS 仓库因协议/路径不一致导致版本识别失败，或你明确需要跨仓库做版本合并（比如内部镜像 + 公共源联合选最高版）。它不是常规配置项。
- 典型错误：给
packagist.org或阿里云镜像设"canonical": false—— 它们忽略这个字段，且会绕过元数据校验 - 正确用法只针对 vcs 类型：
"type": "vcs"+ SSH URL 配了 HTTPS source，或用了符号链接导致路径不匹配 - 报错现象：
Could not find package myvendor/mypackage at version dev-main，但git ls-remote能看到分支 - 设完
"canonical": false后，务必确认该仓库确实提供了你要的版本 tag 或 branch，否则仍会失败
canonical 是个精细开关，不是排序杠杆。真要控制加载来源，盯住 repositories 顺序、packagist.org 开关、仓库类型这三点就够了。多加一个 "canonical": false，反而会让 Composer 在不该继续的时候继续找，埋下版本漂移隐患。
