canonical 是 Composer 用于校验仓库 URL 是否为包“权威来源”的选项，默认 true；仅在私有 VCS 仓库因协议/路径不一致（如 SSH 配置但包内写 HTTPS）导致版本无法识别时，需设为 false。
Composer 的 canonical 仓库选项不是用来“切换源”或“加速安装”的，它只在特定场景下影响包元数据解析——比如你维护私有包且用了符号链接或 Git 子模块时，必须显式设为 false，否则 Composer 可能报错找不到版本。
什么是 canonical？它什么时候起作用
这个选项控制 Composer 是否将仓库 URL 视为“权威来源”。默认为 true，意味着 Composer 假设所有包的 dist 或 source 地址都应严格匹配仓库配置里的 url。一旦不匹配（例如：Git 仓库用 SSH 地址配置，但实际 composer.json 里写的是 HTTPS 的 source），就会触发校验失败。
常见触发场景：
- 私有 GitLab/GitHub 仓库配置了 SSH URL，但包内
composer.json的source是 HTTPS - 本地开发用
path仓库 + 符号链接，而链接目标路径和仓库声明的url不一致 - 使用
package类型仓库手动定义包，但dist的url和仓库根 URL 对不上
如何设置 canonical 为 false
只能在 repositories 配置中针对单个仓库设置，不能全局开关。直接加 "canonical": false 字段即可：
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:myorg/mypackage.git",
"canonical": false
}
]
}
注意：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
"canonical": false仅对vcs和package类型仓库有效；composer类型（如 packagist.org）忽略该字段 - 不要在
packagist.org或镜像源上设false——这不会加速，反而可能绕过安全校验 - 如果同时用了多个私有仓库，每个都需要单独配，不能继承
不设 canonical 会遇到什么错误
典型报错信息是：Could not find package myvendor/mypackage at version dev-main.，即使 git ls-remote 能看到分支，Composer 也会静默跳过该仓库。
根本原因：Composer 在扫描 VCS 仓库时，会比对远程 URL 和本地克隆/缓存路径是否“可映射”。若 canonical 为 true 且 URL 协议/域名不一致（如 git@ vs https://），它就认为这不是同一个源，直接丢弃该仓库的版本数据。
调试建议：
- 运行
composer diagnose不会提示此问题，需加-v查看仓库加载日志 - 用
composer show -a myvendor/mypackage看是否列出了任何版本；为空则大概率是canonical拦截 - 临时把仓库
url改成和包内source.url完全一致，能验证是否为此原因
真正需要改 canonical 的情况其实很少——多数人装不上包，其实是 minimum-stability、分支名拼写、或未执行 composer clear-cache 导致的。只有当你确认包存在、URL 可访问、且 composer show 完全看不到它时，才值得往这个方向查。
