必须清VCS缓存，因Composer默认缓存Git仓库，历史重写、分支变更等会导致install拉取错误代码；可通过diagnose、检查vcs目录、dry-run日志交叉验证是否污染。
composer install 之前为什么必须清 VCS 缓存？
因为 Composer 默认会缓存 Git 克隆的仓库（尤其是 vcs 类型仓库），如果本地有旧 commit、分支名变更、或远程仓库重写历史（如 git push --force），缓存会导致 composer install 拉取错误的代码，甚至静默回退到旧版本。这不是“网络慢”，而是缓存污染。
如何确认当前 VCS 缓存是否已污染？
Composer 不提供直接“查看缓存内容”的命令，但可通过以下方式交叉验证：
- 运行
composer diagnose—— 若输出中含Checking git settings后提示OK，说明 Git 配置正常；若报Failed to initialize global git directory，则 VCS 缓存路径可能不可写 - 检查缓存目录是否存在脏数据：
ls -la $(composer config cache-dir)/vcs/，里面每个子目录对应一个仓库 URL 的 hash；若看到大量以github.com-或gitlab.com-开头的目录，且修改时间远早于你最近一次git push，大概率已过期 - 执行
composer update --dry-run -v，观察日志中是否出现Cloning [url] (to revision [hash])—— 如果 revision 和你期望的不一致，说明缓存被复用
安全清理 VCS 缓存的三步操作
不要直接 rm -rf 整个 cache-dir，VCS 缓存可单独清理，避免重下所有 dist 包：
- 只清 VCS 缓存：
composer clear-cache --no-interaction会清全部；更精准的是手动删：rm -rf $(composer config cache-dir)/vcs/* - 强制跳过缓存重拉（临时方案）：
composer install --no-cache，适用于 CI 流水线或紧急验证 - 禁用 VCS 缓存（调试用）：
composer config --global cache-vcs-dir ""，之后所有vcs操作都不走缓存（仅限排查，勿长期启用）
CI/CD 中自动规避 VCS 缓存问题的关键点
很多 CI 脚本只清 vendor 和 composer.lock，却忽略缓存，导致构建结果不一致：
- GitLab CI 示例：
before_script: - rm -rf $(composer config cache-dir)/vcs/* - GitHub Actions 建议加一步：
run: composer clear-cache --no-interaction && rm -rf $(composer config cache-dir)/vcs/* - 关键提醒：如果你在
composer.json里用了"type": "vcs"并指向私有 Git 仓库，务必确保该仓库的 SSH key 或 token 在 CI 环境中有效——否则清缓存后反而因鉴权失败卡住
VCS 缓存本身不是 bug，是 Composer 提速的设计，但它对 Git 操作的“副作用”极敏感。最常被忽略的是：composer update 和 composer install 对缓存的使用策略不同，前者可能触发更新，后者默认复用，所以部署前单靠 update 验证不够。
