composer看不到git tag的根本原因是其解析器仅识别严格语义化格式vx.y.z（如v1.2.3），不带v前缀（如1.2.3）、含非法字符（如v1.2.3-beta、v1_2_3）或附注标签（git tag -a）均被跳过；必须用轻量标签git tag v1.2.3并推送至远程，私有包还需删除composer.json中version字段且配置repositories为vcs类型。

Composer为什么看不到你打的 Git tag

根本原因不是 Composer “没扫描到”，而是它压根不认你写的 tag 名——v1.2.3 可以，1.2.3、v1.2.3-beta、v1_2_3 全部被跳过。Packagist 和 Composer 的 tag 解析器只接受严格语义化格式：vX.Y.Z（v 开头，纯数字点分隔，无空格、下划线、横线、加号）。

常见错误现象：git ls-remote --tags origin 能看到 refs/tags/1.2.3，但 composer show vendor/name --all 列表里没有 v1.2.3；或者 Packagist 页面“Versions”标签页为空。

• 必须用 git tag v1.2.3（轻量 tag），禁用 git tag -a v1.2.3
• 必须推送：运行 git push origin v1.2.3，仅本地打 tag 无效
• 私有包的 composer.json 中不能有 "version" 字段——删掉它，否则 Composer 优先读该字段，忽略 Git tag
• 确保 repositories 配置为 "type": "vcs"，不是 package 或 path

中文环境下容易被忽略的字符陷阱

中文输入法下复制粘贴版本号时，极易混入全角符号或不可见空格，导致 composer require 直接报 Could not parse version constraint。

比如你写的是 composer require vendor/pkg:v1.2.3，但冒号是中文全角（：）、波浪号是中文（～）、末尾多了空格，或版本号里夹着零宽字符——这些都会让解析器崩溃。

• 版本约束中所有符号必须是 ASCII：^、~、:、.，不能是 ～、：、．
• composer require vendor/pkg:1.2.3 是合法的，但 vendor/pkg: v1.2.3（冒号后空格）会失败
• 别在命令行里用中文引号包裹版本，如 "v1.2.3" —— 单双引号都应为英文
• 编辑 composer.json 时，用 VS Code 或 PHPStorm 打开“显示不可见字符”功能，检查换行符和空格

私有仓库打完 tag 还装不上？先清 VCS 缓存

composer clear-cache 对私有 VCS 包几乎无效。Composer 每次安装私有包时，会克隆或 fetch 远程仓库到本地缓存目录，而这个缓存不会随全局 cache 清除自动更新。

Git Changelog Generator

使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……

下载

真正要清的是 VCS clone 缓存路径：~/.composer/cache/vcs/https---your-git-domain-com-vendor-pkg.git/（Linux/macOS）或 %APPDATA%\Composer\cache\vcs\https---...（Windows）。

• 直接删掉对应仓库缓存目录：rm -rf ~/.composer/cache/vcs/https---gitlab.example.com-group-pkg.git
• 再执行 composer update vendor/pkg，强制重新 fetch 远程 tag 列表
• 若用 SSH，确认 git clone git@gitlab.example.com:group/pkg.git 在当前用户下能成功，否则 Composer 会静默失败
• CI 环境中，建议在 install 前加一步 rm -rf ~/.composer/cache/vcs/，避免缓存污染

兜底验证：别信 GitHub 页面，信 Composer 自己

GitHub/GitLab 页面显示 tag 已存在，不等于 Composer 能识别它。唯一可靠验证方式是让 Composer 自己说话。

运行这三步命令，缺一不可：

• composer show vendor/pkg --all —— 输出中必须出现 v1.2.3，且标注为 stable
• composer depends --tree vendor/pkg —— 确认依赖树引用的是 v1.2.3，不是 dev-main 或其他分支
• grep -A 2 '"vendor/pkg"' composer.lock —— 查看 source.reference 字段是否为该 tag 对应的 commit hash，而非分支名

如果三者任一不满足，说明 tag 没生效，问题仍在 Git 命名、推送、或配置环节——不是网络延迟，也不是权限问题。