根本原因是composer 2.x默认canonical模式导致私有仓库阻断packagist查找，需显式设"canonical": false才能启用多源回退；验证用composer show和repo:list，解决依赖冲突需从约束、锁文件、求解器干预三处入手。
为什么composer.json里配了私有仓库，却还是装了Packagist上的旧版包？
根本原因不是版本冲突，而是仓库优先级没生效。Composer 2.x 默认启用 canonical 模式：一旦在某个仓库（比如你配的私有源）找到包名匹配项，就**完全跳过后续所有仓库**，包括 Packagist。但如果私有仓库返回的包信息里没有满足你版本约束的版本，Composer 不会“退而求其次”去 Packagist 找，而是直接报错或装一个低版本——这容易被误认为是“冲突”，其实是查找链提前中断。
验证方法：运行 composer show vendor/package-name，看输出里的 source 字段指向哪个仓库；再用 composer repo:list 确认仓库声明顺序。
- 确保私有仓库 URL 可访问，且返回的
packages.json包含你所需版本的元数据（尤其注意dist和source地址是否可拉取） - 如果私有仓库只托管部分包，必须显式设
"canonical": false，否则它“挡”住了 Packagist - 不要依赖
packagist.org自动 fallback —— Composer 2.x 不再这么做
repositories 配置中 canonical: false 的真实作用
这个配置不是“关闭仓库优先级”，而是告诉 Composer：“这个仓库只是补充，即使它有同名包，也别急着停，继续往后查”。典型场景是混合使用私有组件库 + Packagist 公共生态。
错误写法："repositories": [{"type": "composer", "url": "https://my-priv.repo"}]
→ 默认 canonical: true，哪怕你的私有源只提供 myorg/utils，它也会阻断 monolog/monolog 去 Packagist 查找。
正确写法："repositories": [{"type": "composer", "url": "https://my-priv.repo", "canonical": false}]
→ 私有源查不到时，自动继续查 Packagist
-
canonical: false必须写在每个需要“非阻断”的仓库定义里，不能全局设置 - 多个非规范仓库按声明顺序依次查询，第一个返回匹配结果的胜出
- 若两个非规范仓库都提供同一包的同一版本，Composer 会选声明靠前的那个，但不会合并版本列表
用 composer update --with 绕过锁文件限制临时验证版本兼容性
当你怀疑某个包的新版本其实能跑通，但 composer.lock 锁死了旧版，又不想全量 update 引发连锁反应，--with 是最轻量的验证手段。
例如：项目当前锁着 guzzlehttp/guzzle:^7.2，你想试 ^8.0 是否可用：
composer update --with=guzzlehttp/guzzle:^8.0
这条命令不会改 composer.json，也不会重写整个 lock 文件，只临时把 guzzlehttp/guzzle 提升到 ^8.0 范围内可解的最高版本，并重新计算其依赖树。成功后，你可以选择 composer update guzzlehttp/guzzle 固化变更，或直接 git checkout composer.lock 放弃。
-
--with仅在 Composer 2.4+ 可用；低于此版本请改用composer require guzzlehttp/guzzle:^8.0 --no-update && composer update guzzlehttp/guzzle - 它不解决底层冲突，只是让求解器在更宽泛的版本空间里再试一次
- 执行后务必运行测试，因为
--with不保证 API 兼容性，只保证依赖图可解
忽略平台要求 ≠ 忽略版本冲突，--ignore-platform-reqs 的真实用途
这个选项常被误用于“强行装新版”，但它真正解决的是 PHP 版本、扩展缺失等环境级不匹配，对包之间的语义化版本冲突（如 A 要 ^1.0、B 要 ^2.0）完全无效。强行加它，只会让 Composer 跳过检查后报更晦涩的运行时错误。
典型误用场景：
本地 PHP 8.3，但某旧包声明 "require": {"php": "^7.4 || ^8.0"} → 缺少 8.3，此时 --ignore-platform-reqs 合理。
但若报错是 Root composer.json requires package-a ^1.0, but package-b v2.1.0 requires package-a ^2.0 → 这是纯逻辑冲突，加该选项毫无意义。
- 它绕过的是
php、ext-*、lib-*这类 platform reqs，不是包间 version reqs - CI/CD 中慎用：跳过平台检查可能让构建通过，但部署到目标环境时直接崩溃
- 替代方案更安全：用
config.platform.php模拟目标环境，例如"config": {"platform": {"php": "8.0.0"}}
仓库配置和版本冲突是两层问题：前者决定“去哪找”，后者决定“找什么”。很多人卡在中间——以为配了私有源就能覆盖版本逻辑，其实只是改变了查找起点。真要压住冲突，得从约束表达（^ vs ~）、锁文件维护节奏、以及求解器干预手段（--with / --minimal-changes）三处下手。
