Composer update卡在VCS源拉取时，本质是复用损坏或过期的Git裸仓库缓存；需精准删除对应vcs/下裸仓库目录、同步删composer.lock，并加--no-cache强制重拉。
Composer update卡在VCS源拉取时怎么定位问题
不是网络慢，而是 Composer 正在复用损坏或过期的 Git 仓库快照——vcs/ 目录下缓存的裸仓库（bare repo）可能已腐化、分支不存在、或与远程 HEAD 不一致，导致 update 卡在 “Cloning into…” 或反复报 fatal: reference is not a tree。
实操建议：
- 先确认是否真走 VCS：运行
composer show vendor/package -v，看输出里source是git还是dist；如果是source: git https://...，说明正在用 VCS 模式 - 盯住
composer update -v日志末尾，找到类似Cloning https://github.com/vendor/package.git或Updating /home/user/.composer/cache/vcs/https---github.com-vendor-package.git/的行，提取出仓库 URL 和本地缓存路径 - 进缓存目录查裸仓库状态：
cd ~/.composer/cache/vcs/https---github.com-vendor-package.git/，执行git show-ref --heads看是否有你 require 的分支（如dev-main）；若无，说明缓存里没这个分支，Composer 就会失败 - 别只删 ZIP——
composer clear-cache对vcs/无效，它只清files/和部分元数据
手动清理VCS缓存要删哪几个文件
必须精准删除对应裸仓库及其索引，不能只删 vcs/ 下某层目录，否则 Composer 仍会尝试从残留的 refs/ 或 objects/ 里读旧数据。
实操建议：
- 找到完整缓存路径：运行
composer config --global cache-dir，再拼上vcs/子目录，例如~/.composer/cache/vcs/https---github.com-vendor-package.git/ - 直接删整个裸仓库目录：
rm -rf ~/.composer/cache/vcs/https---github.com-vendor-package.git/（Linux/macOS）；Windows 用户删对应%APPDATA%\Composer\Cache\vcs\https---github.com-vendor-package.git\ - 别碰
repo/和files/——它们不参与 VCS 拉取流程；但如果你同时用了path+git混合模式，也建议顺手清掉files/下同名 ZIP（避免 fallback 到 dist） - 删完后加
--no-cache强制重拉：composer update vendor/package --no-cache，防止 Composer 从其他缓存路径“抄近道”
VCS源更新失败但报错信息很模糊怎么办
常见现象是日志停在 “Loading composer repositories with package information” 后无响应，或只报 Failed to clone …, could not read from remote repository，但 git clone 命令却能成功——这说明问题不在 Git 本身，而在 Composer 的缓存解析逻辑里。
实操建议：
- 加
-vvv看真实命令：composer update -vvv，找Executing command (CWD): git --version和后续git ls-remote行；如果这里卡住，说明 Composer 在查远程 ref，而缓存里的refs/已失效 - 手动验证远程可访问性：
git ls-remote https://github.com/vendor/package.git dev-main，看是否返回 commit hash；若无，说明分支名写错了，或远程已删该分支 - 检查
composer.json中的require版本写法：写"vendor/package": "dev-main"时，Composer 默认去查origin/main；如果远程分支叫master，就得写成"dev-master"或改用dev-main#commit-hash - 若用私有 GitLab/Gitee，确认 URL 是否带认证前缀（如
https://token:x-oauth-basic@gitlab.com/...），Composer 缓存不会自动注入 token，旧缓存可能因鉴权失败被静默跳过
为什么删了vcs缓存还是拉不到新提交
因为 Composer 在 VCS 模式下会把 commit hash 锁进 composer.lock 的 source.reference 字段，即使你清了缓存、换了分支，只要 lock 文件没更新，它就坚持用老 hash。
实操建议：
- 必须同步删
composer.lock和vendor/（至少删vendor/vendor/package）；否则update会比对 lock 里的source.reference，发现“没变”，直接跳过拉取 - 删 lock 后跑
composer update vendor/package --no-cache --with-dependencies，确保子依赖也跟着重解析，而不是沿用旧锁 - CI/CD 中禁用 VCS 模式：Docker 构建或 GitHub Actions 应改用
dist模式（删repositories块、用正式 release 版本），避免缓存不可控 - 最隐蔽的坑：某些 IDE（如 PHPStorm）会自动在项目根目录生成
.idea/workspace.xml，里面可能缓存了旧的 Git commit ID，干扰 Composer 解析——删掉.idea/再试
VCS 缓存问题最难缠的地方在于它不报错、不提示、也不告诉你“我正在读哪个缓存文件”，所有行为都藏在 silent fallback 逻辑里。真正可靠的排查动作永远是三步：删对应 vcs/ 目录 → 删 composer.lock → 加 --no-cache 重拉。任何省略其中一环的操作，都可能让你在同一个坑里循环三天。
