必须显式设置cache-vcs-dir,仅配cache-dir不改变VCS缓存位置;它独立于cache-dir,须用绝对路径,且受COMPOSER_CACHE_DIR环境变量覆盖。

composer config --global cache-vcs-dir 必须显式设置
只配 cache-dir 不会改变 VCS 缓存位置,cache-vcs-dir 是独立配置项,且必须用绝对路径。Composer 默认把 Git clone 的临时仓库存在 ~/.composer/cache/vcs/ 下,但这个路径不会随 cache-dir 自动更新。
正确写法(Linux/macOS/WSL):composer config --global cache-vcs-dir /data/composer-cache/vcs
Windows CMD:composer config --global cache-vcs-dir "D:\composer-cache\vcs"
常见错误:
- 写了
cache-vcs-dir ./vcs—— 相对路径会被忽略,实际仍走默认位置 - 漏掉
vcs子目录层级,比如设成/data/composer-cache而不是/data/composer-cache/vcs,导致后续 clone 失败或静默 fallback - PowerShell 中直接写
%APPDATA%\Composer\Cache\vcs,变量未展开,结果写入了字面路径
VCS 缓存迁移要连带整个 vcs/ 目录一起搬
VCS 缓存不是单个文件,而是按源 URL hash 分目录存放的完整 Git 仓库(含 .git/),迁移时不能只复制 zip 包或 metadata,必须整目录搬运。
操作要点:
- 先停掉所有正在运行的 Composer 命令(尤其是
composer update),避免写入冲突 - 用
rsync -a ~/.composer/cache/vcs/ /new/path/vcs/(Linux/macOS)或 robocopy(Windows)保证权限和符号链接完整 - 迁移后立即验证:执行
composer clear-cache,观察日志是否清理的是新路径下的vcs/内容 - 如果旧缓存里有大量私有 Git 仓库,确认新路径下对应目录的
.git/config里 remote URL 仍可访问(尤其涉及 token 或 SSH key 变更时)
环境变量 COMPOSER_CACHE_DIR 会覆盖 cache-vcs-dir 配置
一旦设置了 COMPOSER_CACHE_DIR,Composer 会自动在其下拼接 vcs/ 作为实际 VCS 缓存路径,此时 cache-vcs-dir 配置完全失效。
验证方式:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- Linux/macOS:
echo $COMPOSER_CACHE_DIR;Windows:echo %COMPOSER_CACHE_DIR% - 若输出非空,检查该路径下是否存在
vcs/子目录,且里面是否有内容 - 若想绕过环境变量强制使用
cache-vcs-dir,得在运行命令前 unset:COMPOSER_CACHE_DIR= composer install
CI/CD 场景中特别容易踩坑:构建脚本里 export 了 COMPOSER_CACHE_DIR,但没意识到它同时接管了 vcs、files、repo 所有子路径。
cache-read-only true 时 vcs/ 目录必须可读且非空
启用只读模式(composer config --global cache-read-only true)后,Composer 不再尝试 clone 新仓库,而是直接复用已有 vcs/ 内容。但前提是该目录存在、可读、且至少包含你项目依赖所需的 Git 仓库。
典型失败现象:
Failed to clone https://xxx.git via https, ssh protocols, aborting.- 日志里出现
Cloning into '/tmp/xxx'...,说明它放弃了缓存,转而临时克隆
解决办法:
- 确保迁移后的
vcs/目录属主和权限正确(Linux/macOS:chmod 755 /path/to/vcs;Windows:当前用户需有“读取与执行”权限) - 检查目标
vcs/下是否真有对应仓库目录(例如github.com-user-repo.git/),没有就手动git clone一次进去 - 不要指望只读模式能“自动补全”缺失的仓库——它只读,不拉
VCS 缓存路径看似只是个配置项,但它直接影响 clone 行为、网络请求次数和离线能力。最容易被忽略的是环境变量的覆盖优先级,以及只读模式下对目录内容完整性的硬性要求。










