composer如何安装带Tag的版本_composer标签选择【技巧】

指定 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 文件状态——任何一个环节断开，都会让指定版本“失效”。