Composer 读不到 Git 标签是因为它默认不主动 fetch --tags,仅依赖本地 VCS 缓存;缓存缺失 tag 时直接跳过匹配,需手动清理对应 vcs 缓存目录或配置 COMPOSER_VCS_GIT_FETCH_ARGS="--tags --prune" 强制拉取全量标签。

Composer 读不到 Git 标签,不是 Git 本身问题,而是它默认跳过本地缓存中缺失 tag 的仓库——哪怕你刚 git push --tags 完,composer update 仍报 “Could not find package” 或 “No matching package found”。
为什么 composer update 看不见新打的 tag
Composer 对 VCS 仓库(Git/GitLab)的解析分两步:先查本地缓存(~/.composer/cache/vcs/),再决定是否走网络。如果缓存里没这个 tag,它不会自动 fetch,而是直接放弃匹配,哪怕远程已有。
- 缓存目录下对应仓库的
refs/tags/子目录为空或不全,就代表 tag 没被收录 -
git clone时默认只 fetchHEAD分支,不带--tags,所以本地克隆副本里压根没有 tag - Composer 不会主动运行
git fetch --tags,它只信任缓存快照 - 手动删掉
~/.composer/cache/vcs/https---gitlab.example.com-org-pkg.git/后重试,常能立刻生效——这说明问题不在远程,而在缓存陈旧
composer clear-cache 不够,要清特定 VCS 缓存
composer clear-cache 只清全局 HTTP 缓存(如 p/provider-*.json),对 VCS 本地 Git 缓存无效。必须手动定位并清理:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 先确认缓存路径:
composer config --list | grep cache-dir,通常为~/.composer/cache - VCS 缓存位置固定:
$COMPOSER_CACHE_DIR/vcs/下按 URL 哈希命名的目录,例如https---gitlab.example.com-org-pkg.git/ - 删掉整个对应目录:
rm -rf ~/.composer/cache/vcs/https---gitlab.example.com-org-pkg.git - 再跑
composer update vendor/name,Composer 会重新 clone 并 fetch --tags
让 Composer 每次都拉全量 tag(适合 CI 或私有环境)
不想每次手动清缓存?可在项目级 composer.json 中加配置,强制 Composer 使用完整 clone 行为:
- 在
config节点下添加:"preferred-install": {"*": "source"}(确保走 git clone 而非 dist) - 加
"github-protocols": ["https", "ssh"](避免协议降级导致 fetch 失败) - 关键一步:设置环境变量
COMPOSER_VCS_GIT_FETCH_ARGS="--tags --prune",这会让所有 git fetch 命令带上--tags - CI 场景建议在构建脚本开头加:
export COMPOSER_VCS_GIT_FETCH_ARGS="--tags --prune",比改全局配置更安全
验证 tag 是否真被识别
别只信 composer update 输出。直接检查 Composer 解析结果:
- 运行
composer show vendor/name --all,输出里应列出dev-main、v1.2.0等所有 tag 和分支 - 若只显示
dev-main,说明 tag 还没进缓存;若显示了但require仍失败,检查minimum-stability是否允许stable版本 - 手动进缓存目录:
ls -la ~/.composer/cache/vcs/https---*/refs/tags/,确认目标 tag 文件存在(如v1.2.0是个文本文件,内容为 commit hash)
最易忽略的是:即使 git ls-remote --tags 能看到 tag,Composer 也不保证用它——它只认自己缓存里的快照。缓存不更新,tag 就等于不存在。

















