如何通过Composer版本约束规则检测依赖兼容性？

本文共计1133个文字，预计阅读时间需要5分钟。

这不是包未下载完，而是Composer在尝试满足某个require约束时卡住了。不要急，直接删除vendor/或composer.lock，然后运行composer -v重跑。

composer install -v

重点盯住这几类输出：

• 形如 Root composer.json requires monolog/monolog ^2.4, but 2.4.0 conflicts with package-x 的冲突主句
• 所有带 requires 的嵌套链条，比如 laravel/framework 10.42.0 requires php ^8.1 → your-project requires php ^7.4
• 末尾的 Conclusion: don't install X 行——它不是结论，是求解器放弃前的最后一搏，真正原因藏在上面几百行里

composer why-not vendor/package:version 能查什么、不能查什么

composer why-not 是定位“某个具体版本为何不可用”的最快方式，但它只回答“为什么这个版本装不上”，不回答“哪个包在锁死它”。

典型用法：

composer why-not guzzlehttp/guzzle:7.9.0

它会输出类似：

myapp/myproject dev-main requires guzzlehttp/guzzle (^7.2) monolog/monolog 3.5.0 requires guzzlehttp/guzzle (^7.5 || ^8.0) symfony/http-client 6.4.0 requires guzzlehttp/guzzle (^7.4)

注意：它不会告诉你 monolog/monolog 是被谁引入的——要查这个，得补一句：

composer depends -r monolog/monolog

常见盲区：

• 如果输出为空，说明该包根本没出现在当前依赖图里（可能被 conflict 排除，或仅存在于 require-dev）
• 它不检查 platform 配置是否与真实 PHP 版本冲突，这类问题得靠 composer check-platform-reqs 单独验证

^、~、= 这些版本约束到底怎么算

Composer 的版本解析不是字符串匹配，而是基于语义化版本（SemVer）的数学推导。写错一个符号，可能让 composer update 升到破坏性大版本。

关键规则：

• ^1.2.3 ≡ 允许升级到 1.x.x 中所有兼容版本，即 ≥1.2.3 且 <2.0.0；但 ^0.1.2 只允许 <0.2.0（0.x 是不稳定段）
• ~1.2.3 ≡ 允许补丁级升级，即 ≥1.2.3 且 <1.3.0；~1.2 等价于 ~1.2.0
• =1.2.3 是硬锁定，但 Composer 仍可能因依赖传递强制升级——除非你同时写 "prefer-stable": true 并禁用 --with-dependencies

容易踩的坑：

• 写 "monolog/monolog": "^1" —— 它等价于 "^1.0.0"，但如果你项目实际需要 ^2.0 功能，这个约束会让 Composer 死守 1.x，报错却不提示你该升主版本
• 用 "dev-main" 或 "*@dev"：它们绕过 SemVer 检查，也不进 composer.lock 的哈希校验，上线后极易因远程分支变更导致行为漂移

PHP 版本升级后，为什么 composer update 不重算依赖

Composer 不把 PHP 版本当“可变依赖”，它只在首次解析或 lock 文件缺失时，才基于当前环境重新计算整个依赖图。一旦 composer.lock 存在，它就复用里面为旧 PHP 版本解出的包版本。

后果很直接：你在 PHP 8.2 下运行 composer update，它仍可能装上一个只声明支持 php: ^7.4 的包——只要 lock 里记着它。

必须做的三件事：

• 执行 composer clear-cache：清掉平台感知缓存，否则它可能沿用 PHP 8.1 的扩展可用性判断
• 用 composer update --with-all-dependencies：普通 update 只动顶层 require，而这个参数会放开所有间接依赖（如 symfony/console 被 laravel/framework 引入）的版本锁
• 别碰 --ignore-platform-reqs：它跳过 php 和 ext-* 校验，装上不兼容包，等运行时报 Call to undefined function 才发现，调试成本翻倍

最隐蔽的问题往往出在 config.platform.php：它会覆盖真实 PHP 版本，让 check-platform-reqs 检查假环境。本地开发建议删掉这一段，只在 CI 中保留。