缓存对VCS依赖完全无效，必须改用--prefer-dist；VCS模式下Composer直接克隆仓库，不走ZIP缓存路径，~/.composer/cache/files/为空，唯一解法是私有包改用dist发布或优化Git配置。
缓存对VCS依赖完全无效，必须改用--prefer-dist
Composer从Git仓库（VCS）拉取代码时，--prefer-dist参数会被忽略，缓存机制自动失效。因为VCS模式下，Composer直接克隆或拉取仓库快照，不经过files/目录下的ZIP缓存路径。即使cache-dir配置正确、镜像源生效，所有vcs/子目录里的内容（如~/.composer/cache/vcs/https---github.com-vendor-package.git/）都只存元数据和Git refs，不缓存实际代码包。
常见错误现象：composer update耗时稳定在2–5分钟，且~/.composer/cache/files/下始终为空；CI日志显示大量Cloning into '/tmp/...'...。
- 唯一解法：把私有包从VCS源改为dist发布（即打tag + 推送ZIP到镜像源）
- 若必须用VCS（如开发中未打tag），则需禁用缓存逻辑，转而优化Git本身：设置
git config --global core.compression 9、启用core.sparseCheckout、或用depth=1浅克隆（需在repositories中配"options": {"git": {"depth": 1}}） - 检查是否误启
--prefer-source：运行composer config --list | grep prefer，确认无preferred-install设为source
私有仓库如何支持dist模式并命中缓存
要让私有包走--prefer-dist并复用缓存，关键不是改Composer配置，而是让私有仓库“看起来像Packagist”。必须满足三个条件：
- 仓库需提供
dist字段：在composer.json的repositories块中，type不能是vcs，而应为package或对接私有Satis/SatisPress服务 -
distURL必须指向可直连的ZIP包（如https://packages.example.com/dist/vendor-package-1.2.0.zip），且响应头含Content-Length和ETag - 该ZIP包的SHA256哈希必须与
composer.lock中记录一致；否则Composer会跳过缓存，重新下载
示例合法配置：
{
"repositories": [
{
"type": "package",
"package": {
"name": "acme/utils",
"version": "1.2.0",
"dist": {
"url": "https://packages.acme.internal/dist/acme-utils-1.2.0.zip",
"type": "zip",
"reference": "a1b2c3..."
}
}
}
]
}
Docker构建中VCS缓存“伪优化”的陷阱
很多人在Dockerfile里写RUN git clone ... && composer install，再挂载~/.composer/cache，以为能提速——这是错的。VCS模式下，~/.composer/cache/vcs/目录只缓存Git索引和ref信息，每次git clone仍需完整网络传输，且不同commit SHA会导致缓存key不匹配，实际复用率为0。
真正有效的做法只有两个：
- 放弃VCS：把私有包发布为dist（GitHub Releases + ZIP + Satis），并在CI中预生成
composer.lock，确保所有环境走--prefer-dist - 放弃本地构建：用多阶段构建，在builder阶段完成
git clone && composer install --no-dev --prefer-dist，然后只COPYvendor/和.composer/cache/files/进最终镜像；注意vendor/必须带完整文件权限，否则运行时autoload失败
容易被忽略的一点：composer install在Docker中若未指定--no-interaction，遇到私有仓库认证会卡住，看似“缓存没生效”，实则是交互阻塞。
APCu和classmap-authoritative对VCS场景毫无帮助
--apcu-autoloader和--classmap-authoritative只影响vendor/autoload.php加载阶段，和依赖下载无关。它们不会加速git clone或svn export，也不会减少VCS元数据请求次数。在VCS模式下启用这些参数，只会让composer install最后几秒变快几十毫秒，但整体耗时几乎不变。
更危险的是：--classmap-authoritative在VCS开发流程中极易出错——比如你刚加了一个新类但还没git add，composer dump-autoload -a生成的映射就不包含它，运行时报Class not found，而错误提示和缓存问题混在一起，排查成本陡增。
结论很实在：VCS ≠ 缓存友好。想提速，就得切换分发方式，而不是在下载环节上叠Buff。
