composer show 能查到包但装不上，说明版本约束与 Packagist 实际发布的 tag 不匹配，常见原因包括版本字符串错误、稳定性未声明、大小写不符等，应通过 composer show -a 查全量版本并核对稳定性标记。
composer show 能查到包但装不上，说明版本约束没对上
运行 composer show vendor/package 有输出，但 composer require vendor/package:1.2.3 报 “Could not find a matching version”，基本可以确定是版本字符串和 Packagist 实际发布的 tag 不匹配。
常见错因：
- 写了
^2.0，但该包最新 stable 版只有1.27.4
- 想装
dev-main，却没在 <code>composer.json里设"minimum-stability": "dev"，也没加@dev后缀 - 把分支名写成
main（漏了dev-前缀），正确应为dev-main - 包名大小写错误，比如
laravel/sanctum写成laravel/Sanctum（Linux 环境下会失败）
验证方式：用 composer show -a vendor/package 查全量版本列表，注意每行末尾的稳定性标记（stable、beta、dev）。
报错 “Your requirements could not be resolved” 别急着删 composer.lock
这个错误不是“找不到包”，而是 Composer 在做逻辑推演时发现：**没有任何一组版本能同时满足你所有约束**。删 composer.lock 会让当前可运行状态丢失，反而更难定位。
优先执行这三步：
-
composer update --dry-run -v：不改文件，但完整走一遍解析流程，关键冲突信息在输出末尾几行，盯住反复出现的包名（如monolog/monolog、guzzlehttp/guzzle） -
composer why-not vendor/package:version：查谁明确拒绝这个版本（比如某个已装包写了"conflict": {"laravel/framework": ">=10.0"}） -
composer prohibits package-name：反向查哪个依赖强制锁定了旧版，把你想要的版本挡在外面
如果怀疑是 require-dev 里的工具包拖后腿，加 --no-dev 试试：composer update --no-dev --dry-run -v。
私有包或 dev 分支装不上，大概率缺仓库配置或稳定性声明
私有 Git 包（如 GitHub 私库）、Satis 源、或只有 dev-main 没打 tag 的包，必须显式声明来源，否则 Composer 默认只查 packagist.org。
检查点：
-
composer.json里有没有repositories字段？VCS 类型要写"type": "vcs"，URL 必须可访问（HTTPS Token 或 SSH 密钥得配好） - 若只给某一个包开绿灯，别全局改
minimum-stability，直接在require里写"vendor/private-package": "dev-main@dev" - 确认分支真实存在：用
git ls-remote https://github.com/vendor/repo.git看远程分支列表
临时切回官方源验证是否源的问题：composer config --global repo.packagist composer https://packagist.org，再试 composer require。
缓存、镜像、PHP 平台配置都会干扰版本解析
Composer 缓存可能残留过期元数据，尤其切换过镜像源之后；config.platform.php 若人为锁死 PHP 版本（如 "8.0.0"），而你要装的包要求 ^8.1，也会静默失败。
排查顺序建议：
- 先清缓存：
composer clear-cache - 确认当前镜像源是否正常：
composer config -g repo.packagist，必要时切阿里云：composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - 检查平台配置：
composer config platform.php，确保和实际php -v输出一致 - 看是否被
conflict字段卡住：运行composer show vendor/package version，留意输出里是否有conflicts行
最易被忽略的是：你以为在装新包，其实它依赖的某个子包，在你项目里已被另一个依赖通过 conflict 显式封杀了——这种冲突不会提前报错，只在 resolve 阶段崩掉。
