canonical属性与同名包冲突无关，因Composer在解析阶段即以name字段为唯一键注册包，同名即抛异常中止；canonical仅控制单仓库URL匹配校验，不参与去重或注册流程。
canonical 属性不能解决多仓库同名包冲突，它只影响单个仓库的 URL 校验逻辑；同名包冲突必须靠改 name 或用 replace，设 canonical 为 false 对此无效。
为什么 canonical 和同名包冲突无关
Composer 在解析阶段就用 name 字段做唯一键注册，两个包只要 "name": "monolog/monolog" 完全一致，无论来源是 vcs、package 还是 composer 类型仓库，都会直接抛出 Package monolog/monolog is already registered 并中止。而 canonical 只控制「该仓库声明的 URL 是否必须和包元数据里的 dist/source 地址严格匹配」，它不参与 name 去重，也不影响包注册流程。
-
canonical: false的作用场景：私有 Git 仓库配置了 SSH URL（git@github.com:org/pkg.git），但包内composer.json的dist.url写的是 HTTPS（https://github.com/org/pkg/archive/...），此时 Composer 默认拒绝加载该版本 - 它不会让两个
monolog/monolog共存，也不会让 Composer 继续搜索下一个仓库——那是packagist: false和仓库顺序的事 - 在
repositories里对 packagist.org 或镜像源设"canonical": false完全无意义，这类仓库忽略该字段
真正触发 canonical: false 的典型错误现象
你执行 composer update 或 composer require 时，明明 git ls-remote 能看到分支，却报：Could not find package myvendor/mypackage at version dev-main，且日志里没有尝试访问该仓库的 HTTP 请求——说明 Composer 因 URL 不匹配直接跳过了这个仓库。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 常见于本地 path 仓库 + 符号链接：仓库声明路径是
/var/www/myrepo，但符号链接指向/home/user/myrepo，两者不一致 - Git 子模块嵌套时，父仓库的
composer.json中source.url和子模块实际 clone 地址协议/域名不同（SSH vs HTTPS） - 手动维护的
package类型仓库中，dist.url拼接错误，和repositories.url根路径无法对齐
如何正确配置 canonical: false
它只能写在单个 vcs 或 package 类型仓库的定义里，且必须和 url 同级；全局或 composer 类型仓库设它会被忽略。
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:myorg/mypackage.git",
"canonical": false
},
{
"type": "package",
"package": {
"name": "myorg/legacy-lib",
"version": "1.0.0",
"dist": {
"url": "https://cdn.example.com/legacy-lib-1.0.0.zip"
}
},
"canonical": false
}
]
}
-
canonical是布尔值，不能写字符串"false"，否则被当 true 处理 - 每个需要绕过 URL 校验的仓库都得单独加，不能继承或批量设置
- 设为
false后，Composer 会接受该仓库提供的任何版本元数据，不再校验 dist/source 地址是否“权威”，但这也意味着你放弃了路径一致性保护
同名包冲突的唯一有效解法
如果你看到 Package ... is already registered，别折腾 canonical，立刻检查并修正以下三点：
- 运行
composer show和grep -r '"name":' vendor/，确认重复的name字符串来源 - 对 fork 包：进其根目录，修改
composer.json的name字段，例如从"monolog/monolog"改成"acme/monolog"，并同步更新autoload.psr-4映射和命名空间 - 对主项目：若需替代底层依赖，在
composer.json中加"replace": {"monolog/monolog": "*"}，同时确保新包已通过repositories正确引入且require用了新名字
最容易被忽略的是 autoload 配置错位——改了包名但没改命名空间或 psr-4 路径，结果 composer dump-autoload 后依然 Class not found。
