composer diagnose不检查VCS缓存状态,仅验证基础配置、网络连通性及缓存目录可写性;VCS缓存健康需手动检查cache/vcs/下index.lock、pack文件及目录修改时间,并针对性清理。

composer diagnose不显示VCS缓存详情,得手动查
composer diagnose 只检查基础配置、网络连通性和缓存目录可写性,它根本不会扫描 cache/vcs/ 下的 Git 仓库状态。你看到 “Cache: OK” 并不表示那些克隆好的裸仓库没损坏、没卡死、没残留临时文件。VCS 缓存是 Composer 最容易静默出问题的一环——比如某个私有 GitLab 仓库改了 SSH 配置,旧的 vcs/ 目录里还留着失败的 git fetch 进程锁(index.lock),后续所有 composer update 都会卡在 “Cloning into bare repository…” 却不报错。
真正要看 VCS 缓存是否健康,得直接进目录看:
- 先确认路径:
composer config --global cache-dir→ 得到类似/home/user/.composer/cache - 然后进:
ls -la $(composer config --global cache-dir)/vcs/ - 重点盯这些信号:
• 存在大量.git/index.lock或objects/pack/tmp_*.pack文件 → 表示上次克隆中断
• 某个子目录修改时间停留在几个月前,但对应项目最近刚update过 → 可能被跳过未更新
• 目录名含@但路径里有空格或中文 → Windows 或老旧 Git 版本下易出乱码导致无法复用
清理VCS缓存不能只靠composer clear-cache
composer clear-cache 确实会删掉 cache/vcs/ 下的内容,但它是一刀切:不管有没有项目还在用,全清。这会导致下次 composer install 时重新克隆所有包,耗时翻倍,尤其对私有 Git 仓库或网络不稳环境很不友好。
更稳妥的做法是精准清理:
- 只清已知失效的仓库:
rm -rf ~/.composer/cache/vcs/github.com-username-repo.git/(把 URL 转成文件系统安全格式) - 批量清锁文件(安全):
find ~/.composer/cache/vcs -name "index.lock" -delete - 清 pack 文件但保留裸仓库结构:
find ~/.composer/cache/vcs -path "*/objects/pack/*" -name "*.pack" -delete && find ~/.composer/cache/vcs -path "*/objects/pack/*" -name "*.idx" -delete - 注意:
cache/vcs/下的目录是按源 URL 哈希生成的,别手抖删错父级 —— 删了vcs/本身,下次要用时会重建,但删vcs/github.com-这一级就可能误伤多个仓库
为什么composer update总卡在vcs cloning,但没报错?
这不是网络超时,也不是权限问题,而是 Composer 在复用 vcs/ 缓存时默认启用 git fetch --prune,但某些 Git 服务器(如自建 Gitea、旧版 GitLab)不支持该参数,或返回非标准响应。Composer 不抛异常,只是无限等待 git 进程退出。
验证方式很简单:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 开另一个终端,运行:
ps aux | grep "git.*fetch"→ 如果看到挂起的进程,基本就是它 - 临时禁用 VCS 缓存测试:
composer update --no-cache→ 如果立刻走 HTTP 下载 zip,说明问题出在vcs/流程 - 永久绕过(仅调试):
composer config -g cache-vcs false→ 这会强制所有包走 dist ZIP,跳过 Git 克隆
真正修复要改 Git 行为:git config --global fetch.prune false,再配合 composer config -g github-protocols ["https"] 避免 SSH 认证卡死。
CI/CD 中 VCS 缓存共享的坑
很多团队在 CI 里用 composer cache 挂载卷复用 vcs/,结果发现不同分支构建互相污染。原因在于:vcs/ 目录下没有分支隔离 —— 同一个 GitHub 仓库,无论你 checkout dev 还是 main,都复用同一个裸仓库目录。如果 A 构建拉了 dev 分支的 commit,B 构建紧接着拉 main,Git 内部可能因 reflog 冲突拒绝更新,导致 composer install 安装了错误版本的代码。
应对策略只有两个:
- CI 中彻底禁用 VCS 缓存:
composer config -g cache-vcs false,靠 dist ZIP +cache-files-ttl控制体积 - 或者每次构建前强制刷新:
rm -rf $(composer config --global cache-dir)/vcs/*,虽然慢点,但结果确定
VCS 缓存不是“越久越好”,它的价值只在单机、单用户、稳定分支场景下成立;一旦涉及并发、多分支、容器化,就得默认当它不存在。










