composer.lock不管理VCS缓存,它仅记录包版本、dist URL、source reference(如commit hash)和SHA256校验值;VCS缓存由Composer独立维护在~/.composer/cache/vcs/(Linux/macOS)或%APPDATA%\Composer\Cache\vcs\(Windows),存储Git裸仓库,复用逻辑取决于source.reference是否存在及cache-dir可写性。

composer.lock 本身不管理 VCS 缓存
很多人误以为 composer.lock 控制或记录了 VCS(Git/SVN)缓存行为,其实它完全不参与。VCS 缓存由 Composer 单独维护在 ~/.composer/cache/vcs/(Linux/macOS)或 $env:APPDATA\Composer\Cache\vcs\(Windows),内容是 Git 克隆的裸仓库(bare repos)。composer.lock 只存最终解析出的包版本、dist URL、source reference(如 commit hash)和 SHA256 校验值——它告诉 Composer “该装哪个 commit”,但不决定“从哪拉、是否复用本地克隆”。
VCS 缓存实际由 source.reference 和 cache-dir 共同触发
当 composer.json 中某个包通过 vcs 类型仓库引入(比如 GitHub 私有库),且 require 字段指定 "dev-main#abc123" 或 "dev-feature-branch" 时,Composer 才会:
- 检查 ~/.composer/cache/vcs/ 下是否存在对应仓库的裸克隆
- 若存在且已包含目标 commit(source.reference),则直接 git archive 导出,跳过网络拉取
- 若不存在或缺少 commit,则执行 git clone --mirror 到缓存目录,再归档
关键点:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
-
composer.lock里的"source": {"type": "git", "reference": "abc123"}是匹配依据,不是缓存开关 -
cache-dir配置决定缓存根路径,vcs/子目录必须可写,否则每次都会重 clone -
minimum-stability和@dev后缀影响能否解析到分支名,但不改变 VCS 缓存逻辑
删 composer.lock 不等于清 VCS 缓存,但会间接导致重 clone
如果你删掉 composer.lock 并运行 composer update,会发生:
- Composer 重新解析所有依赖,可能选出新 commit(尤其分支未锁定时)
- 新选中的 source.reference 在旧 VCS 缓存中可能不存在 → 触发完整 clone
- 即使 reference 不变,若缓存目录权限异常或被杀毒软件锁住,也会 fallback 到临时克隆(更慢、不复用)
所以真正要控制 VCS 缓存复用率,得看:
- 是否长期保留
~/.composer/cache/vcs/目录(别随脚本自动清) -
composer.json中是否用固定 commit hash(如"dev-main#abc123")而非浮动分支(如"dev-main") - CI/CD 中是否统一用户权限,避免 root 与普通用户混用导致
vcs/子目录属主错乱
手动清理 VCS 缓存的合理场景和做法
除非遇到明确问题,否则不建议定期清 vcs/。它比 files/ 更安全,因为裸仓库可无限重建,且空间增长缓慢(一个 Git 仓库通常几十 MB)。需要动手时:
- 只清失效仓库:比如某私有 GitLab 地址已废弃,用 rm -rf ~/.composer/cache/vcs/gitlab.com---your-org---old-repo.git/
- 批量清所有:rm -rf ~/.composer/cache/vcs/*,下次 composer install 自动重建,无副作用
- 禁止删 vcs/ 下的单个 commit 文件:Git 裸仓库是整体结构,删子文件会导致 corruption,后续报 Corrupted cache file
- Windows 用户注意:$env:APPDATA\Composer\Cache\vcs\ 在 PowerShell 中需用双引号包裹路径,否则空格或括号会中断命令










