答案是先用composer why-not和prohibits定位阻塞包，再针对性调整约束；hyperf版本需显式钉死如"^3.4"，php扩展冲突须修环境而非命令。

Hyperf 项目里 Composer 安装失败，90% 不是 Hyperf 本身的问题，而是依赖树里某个包卡住了版本 —— 直接删 vendor 或强制 update 往往让问题更糟。

composer install 报 “Conclusion: don’t install xxx” 怎么定位阻塞点

这不是安装失败，是 Composer 明确告诉你：当前 composer.json 和 composer.lock 中已有的约束，和你要装的包（或它隐含的依赖）互斥。

• 先跑 composer why-not vendor/package:version（比如 composer why-not monolog/monolog:^3.0），它会输出谁在阻止这个版本，路径清晰到具体子依赖
• 再用 composer prohibits vendor/package:version 查所有“反对者”，尤其注意那些间接依赖（比如 hyperf/framework 拉进来的 psr/http-message 版本锁）
• 别只看报错里的包名 —— 常见陷阱是 spatie/laravel-permission 这类非 Hyperf 官方包，它可能硬依赖 illuminate/support:^10.0，而你的 hyperf/framework 还在 3.x，根本不可能共存

Hyperf 生态里怎么安全锁定核心包版本

Hyperf 主版本升级（如 v3 → v4）不兼容，但很多团队不敢升，又想用新功能包 —— 这时不能靠模糊约束糊弄，得显式钉死边界。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• "hyperf/framework": "^3.4" 是安全的：允许 3.x 内补丁和小版本升级，但绝不会跳到 4.0
• 若发现 hyperf/cache 被意外升到 v4，说明某依赖（比如你手动 require 的 hyperf/async-queue）没写约束，直接在 composer.json 里补上 "hyperf/cache": "^3.4"，然后跑 composer update hyperf/cache --with-dependencies
• 对 PHP 扩展级冲突（如 ext-swoole 版本不匹配），composer diagnose 会报 The requested PHP extension "swoole" is missing，但真实问题是已装的 swoole.so 和 Hyperf 要求的 ^5.0 不符 —— 此时要改的是环境，不是 Composer 命令

composer require 之后 vendor 没更新？检查三个硬性条件

composer require 只改 composer.json，不碰 vendor 和 composer.lock —— 这是设计，不是 bug。很多人卡在这一步。

• 确认是否加了 --no-update：加了就只会写 JSON，必须后续手动 composer update vendor/package
• 检查 composer.lock 里有没有该包的记录：如果 lock 文件旧、且包含冲突版本，composer update 会拒绝重算，此时需先 composer update --lock-only 同步 lock 文件结构
• Hyperf 项目常配了 "minimum-stability": "stable"，但某些包（如 96qbhy/hyperf-auth）发版用的是 dev-master，这时要临时加 --stability=dev，否则 Composer 直接忽略

强制重装 vendor 但不改 lock 文件？用 --force-reinstall

当 vendor 里文件损坏、autoload 失效、或 post-install-cmd 脚本没跑全，rm -rf vendor && composer install 看似快，实则风险高 —— 它会触发完整依赖重解析，可能把原本稳定的 guzzlehttp/guzzle 从 7.x 推到 8.x。

• composer install --force-reinstall 才是正解：严格按当前 composer.lock 重装所有包，覆盖文件、重建 autoload、重跑脚本，lock 文件纹丝不动
• Windows 下失败？关掉 PhpStorm 索引、Swoole 进程、Xdebug，再试；仍不行就加 --prefer-dist 避开符号链接问题
• CI/CD 流水线里推荐固定使用此命令，而不是 composer update —— 后者改 lock，前者保一致

真正难的从来不是命令怎么敲，而是看清哪一行 composer.json 在悄悄拖后腿，或者哪个第三方包的 composer.json 里写了不讲理的 "conflict"。Hyperf 项目越老，这种隐性约束越多，盯住 composer show --tree 输出里的每一层依赖，比盲目 retry 有用得多。