Composer中如何区分tag和branch标签，以及处理分支版本的问题？

本文共计889个文字，预计阅读时间需要4分钟。

Composer 中的不区分标签和分支的语义，仅按字符串匹配规则查 Git 引用 — 你的版本字符串是否被识别为 tag 或 branch，取决于写法、仓库实际存在状态以及 `minimum-stability` 设置。

怎么判断 Composer 当前装的是 tag 还是 branch

别猜，直接看 composer.lock：

• 如果 reference 字段是 40 位十六进制 commit hash（如 "reference": "a1b2c3d..."），且 type 是 vcs，那它就是某个具体提交 —— 但还不能确定是 tag 还是 branch
• 再查 dist 或 source 下的 url 和 reference，结合 composer show vendor/pkg --all 输出比对：tag 行会标 v2.9.1，branch 行标 dev-main
• 最准的方式是运行 git ls-remote --tags --refs <repo-url> 和 git ls-remote --heads --refs <repo-url>，确认你写的字符串在远端到底是 tag 还是 branch 名

写 v2.9.1 却装了 dev-main？这是解析优先级问题

Composer 解析版本字符串时，有明确的先后顺序：

• 先检查输入是否匹配已知分支名（含 dev- 前缀、或未加 v 但远端存在同名分支）→ 按 branch 处理
• 再检查是否匹配已知 tag（如 v2.9.1 或 2.9.1，且远端存在该 tag、无同名分支）→ 按 tag 处理
• 若两者都存在（比如远端既有 2.9.1 分支，又有 v2.9.1 tag），Composer 默认选 branch

所以 composer require monolog/monolog:2.9.1 可能装错，除非你确认远端没有 2.9.1 分支。保险做法永远带 v：composer require monolog/monolog:v2.9.1。

dev-main 和 v2.9.1 的行为差异很实在

不是“概念不同”，是安装机制和锁定逻辑完全不同：

• dev-main 每次 composer update 都可能拉新 commit，composer.lock 记录的是当前 HEAD 的 hash；force push 后旧 hash 失效，composer install 会失败
• v2.9.1 对应固定 commit，不随远端变更；即使删掉这个 tag，只要 composer.lock 还在，install 仍能成功（前提是 dist 包缓存或源可用）
• dev-main 必须配 --stability=dev 或 "minimum-stability": "dev"；v2.9.1 默认就可通过 stable 门槛（前提是它打了 v 前缀）
• 私有仓库中，dev-main 要求 SSH key 可访问；v2.9.1 若走 dist（zip/tar），则只需 HTTP 可达

真正容易被忽略的点：tag 必须带 v 前缀才被当 stable

Git 打 tag 时不加 v（比如 git tag 1.2.3），Packagist 就不会把它识别为稳定版本 —— 它会被当成 1.2.3 这个“分支别名”，下游项目写 "^1.2" 根本匹配不到，只能靠 @dev 强上。这不是 Composer 的 bug，是 Packagist 的解析约定。所以打 tag 动作本身就要规范：git tag v1.2.3，然后 git push origin v1.2.3。