Composer找不到tag主因是版本约束与远程真实tag格式不匹配，需确保tag符合semver规范（如v2.5.0）、已推送至远程、Packagist同步完成，并在composer.json中正确引用带v前缀的版本号。
Composer 找不到 tag，不是包不存在，而是你指定的版本约束没匹配上远程仓库里真实存在的 tag 格式。
composer require 时提示 “Could not find package” 或 “No version match”
这类报错表面是“找不到”，实际是版本解析失败。Composer 默认只认符合 semver 规范的 tag（如 v2.5.0、2.5.0），不识别 release-2.5、stable-2024 或纯数字分支名（如 250）。
- 运行
git ls-remote --tags https://github.com/vendor/package.git查看远程真实 tag 列表，注意是否带^{}后缀（表示轻量 tag） - 在
composer.json中写版本时，用双引号包裹并加v前缀更稳妥："vendor/package": "v2.5.0" - 如果对方用了非标准 tag（比如
main-v2），你不能直接写"main-v2"—— 必须改用dev-main-v2 as 2.5.0这种别名方式 - 私有 GitLab/GitHub 仓库需确认已配置
repositories，且类型为vcs，否则 Composer 根本不会去拉取该源的 tag
composer show 显示有包但 composer require vendor/package:dev-main 报错
这说明包存在，但 dev-main 这个分支名在远程仓库里并不存在，或已被重命名/删除。Composer 不会自动 fallback 到默认分支（如 main 或 master）。
- 先执行
git -C vendor/package rev-parse --abbrev-ref HEAD（如果已下载）确认本地检出的是哪个分支 - 更可靠的方式是查远程：运行
git ls-remote --heads https://github.com/vendor/package.git - 若想强制使用某分支最新 commit，写成
"vendor/package": "dev-main#abc123"（用 commit hash 锁定） - 注意：GitHub 的
main分支在 Composer 2.2+ 才被默认识别为稳定开发分支；旧版需显式写dev-main
私有包打 tag 后 composer install 仍拉不到最新版
根本原因不是网络或缓存，而是 Composer 默认只缓存 Packagist 元数据，对私有 VCS 仓库不做自动元数据更新 —— 它每次都会重新走 git fetch，但前提是你的 composer.json 版本约束能触发该行为。
- 确保
composer.json中版本写法能命中新 tag，例如从"^2.4"改为"^2.5"，否则即使有v2.5.1也不会拉 - 执行
composer clear-cache没用；真正要清的是 VCS 仓库的本地 git clone 缓存：rm -rf ~/.composer/cache/vcs/https---github.com-vendor-package.git/ - 如果用的是 GitHub Packages 或 GitLab Registry，检查 token 权限是否过期，
auth.json是否配置了对应域的凭据 - CI 环境中常见问题：git clone 深度为 1（
--depth=1），导致 fetch 不到 tag —— 需在 CI 脚本中加git fetch --tags
最容易被忽略的是：tag 名称是否真的被远程仓库接受并推送成功（git push origin v2.5.0 和 git push origin tag v2.5.0 效果不同），以及 Composer 解析版本时是否因本地 platform.config 中 PHP 版本声明太老，间接过滤掉了高版本 tag。
