peer依赖不兼容非Composer标准报错，实为运行时暴露的契约断裂：如插件require laravel/framework:^9.0但项目装10.x，或类/方法因版本升级被移除，需通过composer show比对版本、查GitHub文档定位，而非why-not命令。
peer 依赖不兼容不是 Composer 默认报错类型，它不会出现在 composer install 或 composer update 的标准错误里——它只在运行时（比如执行 php artisan、npm run dev 或调用某类方法）才暴露，且常被误判为“类不存在”或“方法未定义”。
为什么 peer 依赖冲突查不到？
Composer 本身不解析或校验 peerDependencies 字段（那是 npm/yarn 的机制），PHP 生态里没有原生 peer 依赖概念。所谓“peer 依赖不兼容”，实际是以下三类情况混在一起被开发者统称：
- 某个包（如 Laravel Mix、Vite 插件、PHP 扩展桥接器）在
require中声明了对laravel/framework或symfony/console的强绑定，但你项目里装的是不兼容主版本（例如插件只支持 ^9.0，你用了 10.x） - 包内部通过
class_exists()或function_exists()做运行时特征检测，结果因 PHP 版本、扩展缺失或 API 移除而跳过关键逻辑，表现像“功能失效” - 私有包或 fork 包的
composer.json里写了"replace": {"some-vendor/some-package": "self.version"}，但没真正实现全部接口，导致下游调用失败
如何定位真实 peer 级不兼容点
别靠猜，用这三步缩小范围：
- 先确认报错发生位置：是 CLI 命令崩了（
php artisan）、Web 请求 500（Class not found）、还是构建工具卡住（vite build报Cannot call method on undefined）？不同场景对应不同检查路径 - 查该命令/库的文档，看它明确声明支持哪些主版本 —— 比如 Laravel Octane 文档会写“Requires Laravel 9.28+”，不是“Laravel 9.x”这种模糊说法
- 运行
composer show vendor/package-name，重点看输出里的requires行，对比你本地composer show laravel/framework的实际版本；若发现vendor/packagerequirelaravel/framework: ^9.0，而你装的是10.42.0，这就是 peer 不兼容根源
composer why-not 对 peer 冲突有用吗？
基本没用 —— composer why-not 只响应 require / conflict 字段的显式约束，对“运行时按需加载”或“文档约定兼容性”完全无感。
- 它不会告诉你 “
spatie/laravel-ray需要laravel/framework的Application::bindIf()方法，而该方法在 10.0 中已移除” - 真正有效的动作是：去该包的 GitHub Releases 页面，翻最近 tag 的
CHANGELOG.md或UPGRADE.md，找类似 “Breaking: Drop support for Laravel 10” 的条目 - 如果包没维护文档，就直接看它的
composer.json原始文件（在 Packagist 页面点 “Source”）：搜索"laravel/framework"出现在require还是require-dev，再看版本范围是否覆盖你当前版本
修复时最容易踩的坑
强行降级主框架或硬打 patch 是最常见错误操作：
- 不要为了适配一个旧插件，把
laravel/framework从 10.x 降到 9.x —— 这会引发整条依赖链的连锁退化，且可能引入已知安全漏洞 - 不要手动修改 vendor 里某个包的源码来“兼容新框架”，下次
composer update就会被覆盖 - 优先找替代方案：比如
barryvdh/laravel-debugbar已停止维护，就换filp/whoops+laravel/tinker组合；laravel-mix升级到 v7 后不再支持 Webpack 4，那就切到vite-plugin-laravel - 如果必须保留旧包，用
conflict显式锁死冲突组合："conflict": {"laravel/framework": ">=10.0.0"}，让 Composer 在 install 阶段就报错，比运行时报错更容易追溯
peer 不兼容的本质是契约断裂，不是版本数字不匹配。盯住文档、看源码、验证运行时行为，比盯着 composer.lock 里的哈希值有用得多。
