Composer提示“版本不存在”90%是版本约束与Packagist实际发布版本不匹配，需用composer show vendor/package确认包存在性，-a参数查全量版本，或访问Packagist官网核对Versions标签页及后缀细节。
Composer 提示“版本不存在”，90% 的情况不是网络或权限问题，而是你写的版本约束根本没在 Packagist（或你配的仓库）里真实发布过。 它不会模糊匹配、不会自动降级、也不会猜你想装什么——写 dev-main，它就真去查有没有叫 main 的分支；写 ^2.5，它就只看有没有 2.x 的 tagged 版本。错一个字符、少一个前缀、多一个空格，都会直接报错。
怎么确认包和版本到底存不存在？
别凭记忆、别信文档、别看 GitHub README——Packagist 才是唯一真相源。
- 运行
composer show vendor/package-name：如果返回 “no matching package found”，说明包名拼错，或该包已从 Packagist 移除（常见于私有包未配repositories） - 加
-a参数查全量版本：composer show -a vendor/package-name，会列出所有稳定/不稳定版本、分支、甚至被标记为abandoned的 tag - 手动打开
https://packagist.org/packages/vendor/package-name，点 “Versions” 标签页，看你要的版本是否在列表里——注意后缀，1.2.3-beta.1和1.2.3是两个不同版本 - 私有 Git 包？确保
repositories配置正确，且该仓库的composer.json中version字段是合法 SemVer 字符串（不能是dev或HEAD）
哪些版本写法最容易触发“不存在”错误？
Composer 对版本字符串解析非常严格，很多看似合理的写法在 v2.2+ 已被禁用或行为变更。
-
"1.2.*"：Composer 2.2+ 已移除支持，必须改用"^1.2"或"~1.2.0" -
"dev-main"：合法，但前提是远程仓库真有main分支；若实际是master，就得写"dev-master" -
"latest"、"v1.2"、"master"、带空格的" >= 1.0 "：全部非法，会直接抛Invalid version string -
"dev-feature/login"：缺dev-前缀就不合法，正确写法是"dev-feature/login"（注意斜杠保留） - 分支别名写法如
"dev-main as 1.0.x-dev"：as前后必须有空格，"dev-mainas1.0.x-dev"会失败
为什么 composer require vendor/package:dev-main 还是报错？
因为默认情况下 Composer 只信任 stable 版本，dev-main 属于开发分支，需要显式允许不稳定性。
- 最简方式：加
@dev后缀：composer require vendor/package:dev-main@dev - 全局放宽（慎用）：在
composer.json里设"minimum-stability": "dev"，但会波及所有依赖 - 更安全的做法：只对这个包指定稳定性，用
"vendor/package": "dev-main as 1.2.3"，并确保1.2.3是个真实存在的稳定版本号（用于兼容性推导） - 如果用了镜像源（如阿里云），记得
composer clear-cache——镜像同步有延迟，刚发布的分支可能还没同步过来
遇到 has been locked to a version that does not exist 怎么办？
这通常不是你写错了，而是 composer.lock 里记了一个已删除或重命名的版本（比如作者删了 v1.0.0 tag，或把 master 改成了 main）。
- 先用
composer why-not vendor/package:1.0.0看是不是其他包通过conflict拦住了 - 临时方案：删掉
composer.lock和vendor/，再跑composer install（会重解依赖，可能升级其他包） - 精准修复：只更新出问题的包：
composer update vendor/package-name，它会忽略 lock 中的无效记录，重新拉取可用版本 - 绝对不要手动编辑
composer.lock里的version或dist.reference——字段格式极易出错，且下次update会被覆盖
真正容易被忽略的是：错误提示里说“版本不存在”，但背后可能是 PHP 版本不匹配、扩展缺失、或者 conflict 字段隐式封锁——这些都不会在报错里明说，得靠 composer why-not 和 composer show --platform 交叉验证。别急着删 lock 文件，先让 Composer 告诉你“为什么不能装”。
