指定 tag 版本应写为 "vendor/package": "v2.1.0"（需与仓库 tag 完全一致），运行 composer update vendor/package 更新 lock 文件后 install 才生效；查可用 tag 推荐 packagist.org 页面或 composer show --all。
composer install 指定 tag 版本的正确写法
直接在 composer.json 的 require 字段里写 "vendor/package": "v2.1.0" 就行，不需要加 dev- 前缀，也不用写 tags/ 路径。Composer 会自动匹配 Git 仓库中已发布的 tag。
常见错误是误写成 "vendor/package": "dev-v2.1.0" 或 "vendor/package": "tags/v2.1.0"，这会导致找不到包或退回到 dev-main 分支。
- Tag 名必须和 GitHub/GitLab 仓库中实际打的 tag 完全一致（包括大小写、点号、横线）
- 如果 tag 是
2.1.0，就不能写成v2.1.0，除非仓库里真有这个 v 开头的 tag - 运行
composer update vendor/package即可精准拉取，不用全量 update
如何查清一个包有哪些可用 tag
最可靠的方式不是靠文档猜，而是直接查 Packagist 页面或用命令行：
- 打开 https://www.php.cn/link/f69b857233949c6a79158d4bb7ab5061，看 “Versions” 标签页列出的所有版本，带 ✅ 图标的才是正式 tag
- 执行
composer show vendor/package --all，输出里所有非dev-开头的行基本都是 tag（如2.3.1、v1.0.0-beta） - 注意：有些包会把 pre-release 版本（如
v3.0.0-rc1）也打成 tag，Composer 默认不安装，需显式设置"minimum-stability": "RC"
为什么写了 tag 却还是装了 dev-main
大概率是以下三个原因之一：
-
composer.lock文件里还锁着旧版本，直接composer install会无视composer.json新改的 tag —— 必须先composer update vendor/package更新 lock 文件 - 该 tag 在 Packagist 上尚未同步（尤其私有 GitLab 包），需要手动触发 hook 或等几分钟缓存刷新
- 包的
composer.json里声明了"version": "dev-main"这类硬编码字段，会覆盖实际 tag，此时应删掉该字段再试
私有仓库打 tag 后 composer 不识别？检查这几点
私有 Git 仓库（如自建 GitLab）打完 tag，Composer 却报 Could not find package vendor/package at version v1.2.3，通常卡在这几个环节：
- 确认 tag 已推送到远程：
git push origin v1.2.3（不是git push --tags就完事，得确保目标分支可见） - 检查
composer.json中仓库 type 是否为"vcs"，且 url 指向的是可读的 HTTPS 或 SSH 地址（如"url": "git@gitlab.example.com:group/repo.git"） - 如果是自建 Satis 或 Private Packagist，要确认它已重新抓取该仓库，否则不会索引新 tag
Tag 看似简单，但 Composer 对它的解析高度依赖 Packagist 缓存、VCS 元数据完整性、以及本地 lock 文件状态——任何一个环节断开，都会让指定版本“失效”。
