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 清除自动更新。
真正要清的是 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 命名、推送、或配置环节——不是网络延迟，也不是权限问题。
