composer config --global cache-vcs-dir 是唯一有效设置方式，必须用绝对路径显式配置，不继承 cache-dir，不自动创建目录，需手动建目录、设权限，并通过 composer diag 或日志验证是否生效。
composer config --global cache-vcs-dir 是唯一有效设置方式
Composer 不提供命令行参数或环境变量直接控制 VCS 缓存路径，cache-vcs-dir 必须通过 composer config --global cache-vcs-dir 显式配置，且值必须是绝对路径。它不会继承 cache-dir 的值，也不会自动拼接子目录 —— 你写什么，它就用什么。
常见错误包括：
- 只设了
cache-dir，以为 VCS 缓存会自动落到$cache-dir/vcs，结果实际仍走默认路径（如~/.composer/cache/vcs） - 用了相对路径或含
~、$HOME的写法，例如composer config --global cache-vcs-dir ./vcs-cache或~/cache/vcs，Composer 完全忽略该配置 - 在 Windows PowerShell 中直接写
%APPDATA%\Composer\cache\vcs，但该变量未展开，导致写入空路径或错误位置
正确写法示例：
Linux/macOS：composer config --global cache-vcs-dir /data/composer-cache/vcs
Windows CMD：composer config --global cache-vcs-dir "D:\composer-cache\vcs"（含空格或反斜杠必须加英文双引号）
VCS 缓存目录必须手动创建并设对权限
Composer 从不自动创建 cache-vcs-dir 目录，也不会报错提示“目录不存在”。如果路径未创建或权限不足，它会静默 fallback 到默认 VCS 缓存位置，导致你改了等于没改。
操作必须严格按顺序执行：
- 先运行
composer config --global cache-vcs-dir写入配置 - 再手动创建目录：
mkdir -p /data/composer-cache/vcs（Linux/macOS）或资源管理器新建D:\composer-cache\vcs（Windows） - 设权限：Linux/macOS 运行
chmod 755 /data/composer-cache/vcs；Windows 检查该目录“属性 → 安全 → 当前用户有完全控制” - CI/Docker 环境中尤其注意属主：若 Composer 配置由
root执行，但实际运行用户是www-data，需执行sudo chown -R www-data:www-data /data/composer-cache/vcs
验证 VCS 缓存是否真在用新路径
composer config --global cache-vcs-dir 只显示你“写了什么”，不代表 Composer “用了什么”。真正生效路径得看 composer diag 输出 —— 它会明确列出 VCS directory: 后面的路径。
更可靠的验证方式：
- 运行
composer clear-cache，观察日志里清理的是不是你设的新vcs路径 - 执行
composer install -vvv，搜索日志中Cloning [repo-url]或Checking out [commit]前后是否有Writing into cache行，并确认路径匹配你设的cache-vcs-dir - 检查
cache-vcs-dir目录下是否生成了类似github.com/your-org/repo.git/的子目录，里面包含refs/、objects/等 Git 内部结构
注意：VCS 缓存只在 --prefer-source 模式下被使用；如果项目用了 --prefer-dist（推荐生产环境），VCS 缓存基本不参与流程。
cache-vcs-dir 和 cache-dir、cache-files-dir 的关系
三者完全独立，互不影响：
-
cache-dir是顶层缓存根目录，仅用于定位默认子路径，不控制任何具体缓存行为 -
cache-files-dir控制 ZIP/TAR 包存放位置（必须以/files结尾），和 VCS 无关 -
cache-vcs-dir专管 Git/Hg/Svn 仓库克隆缓存，内容是完整 .git 目录镜像，体积通常最大
如果你只配了 cache-dir，而没配另外两个，Composer 会按默认规则分别建 $cache-dir/files 和 $cache-dir/vcs —— 但这只是巧合，不是依赖关系。一旦你显式设置了 cache-vcs-dir，它就彻底接管 VCS 缓存路径，不再参考 cache-dir。
最容易被忽略的一点：VCS 缓存目录迁移必须手动搬运，Composer 不会自动把旧 vcs 下的仓库软链接或复制过去。换路径后首次 install 或 update 仍会重新 clone，直到缓存填满。
