Composer 反复拉取 Git 仓库是因为默认禁用 VCS 缓存，仅缓存 ZIP 包；需执行 composer config --global cache-vcs true 并确保 URL 协议、认证方式一致才能复用克隆副本。
Composer 从 Git 仓库安装包时，为什么反复拉取原始仓库？
因为默认情况下 composer install 或 composer update 对 Git 包不启用 VCS 缓存，每次都会走完整克隆流程——尤其是私有仓库或大体积历史的 repo，耗时明显。根本原因是 Composer 的 cache-dir 默认只缓存 ZIP 包和 dist 归档，Git 源（vcs）操作被绕过。
解决办法是显式启用 VCS 缓存，并确保使用支持的协议和配置：
- 在
composer.json中为包指定"type": "vcs"并确保仓库 URL 是git@...或https://...格式（避免git://，已弃用） - 全局启用缓存：运行
composer config --global cache-vcs true（注意不是cache-dir） - 确认缓存路径可写：
composer config --global cache-dir查看位置，常见于~/.composer/cache/vcs/ - 若用 SSH 私钥，确保
ssh-agent已加载且git命令能直连仓库（Composer 调用的是系统git）
私有 Git 仓库认证失败：401 或 “Could not fetch” 错误
这类错误通常不是 Composer 本身的问题，而是 Git 凭据链断裂。Composer 在执行 git clone 时复用系统 Git 配置，所以重点查 Git 层。
常见原因与修复步骤：
- HTTPS 私仓：未配置
git credential.helper，或 helper 未保存凭据 → 运行git config --global credential.helper store，然后手动git clone https://your.repo/repo.git触发一次登录并保存 - SSH 私仓：
git@URL 无法解析或权限拒绝 → 检查ssh -T git@your-git-host是否成功；确认~/.ssh/config中 Host 别名与 Composer 仓库 URL 中的 host 一致（例如github.comvsgitlab.example.com） - GitHub/GitLab Token 权限不足：Token 缺少
repo（私仓）或read_package_registry（GitHub Packages）范围 → 重新生成 Token 并更新git config --global url."https://<code>token@github.com".insteadOf "https://github.com"
如何强制 Composer 使用缓存的 Git 仓库副本？
Composer 不提供“跳过 fetch 直接用缓存”的开关，但可通过组合策略大幅减少实际网络拉取：
- 使用
composer install --no-scripts --no-plugins（跳过脚本执行，避免触发额外 fetch） - 对已安装过的包，
composer update vendor/package比全量update更可能命中本地克隆缓存 - 确保 Git 仓库 URL 稳定：不要混用
git@host和https://host，它们在缓存中被视为不同源，各自维护独立克隆目录 - 手动清理冗余缓存：进入
composer config --global cache-dir下的vcs/子目录，按仓库域名或 hash 文件夹定期删除陈旧克隆（如超过 30 天未访问的git-df3a2b1/）
Git 仓库作为包源时，tag 与 branch 解析慢怎么办？
Composer 在解析 dev-main 或 v1.2.3 时，会调用 git ls-remote 查询远程 ref，而某些 Git 托管服务（如自建 Gitea、老旧 GitLab）响应延迟高，导致卡顿。
优化方式有限但有效：
- 优先使用
dist模式：在composer.json中为该仓库添加"dist": { "url": "...", "shasum": "..." }，让 Composer 绕过 Git 操作直接下 ZIP - 禁用自动 tag 探测：在
repositories中为该 Git 源加"no-api": true，强制 Composer 只读本地克隆（需确保本地缓存已存在对应 tag） - 升级 Git 客户端：Git 2.30+ 对
ls-remote --refs有显著优化，尤其在大量分支场景下
VCS 缓存真正起效的前提，是 Composer 能稳定识别同一仓库的多个请求——URL 写法、协议、认证方式必须完全一致，任何细微差异都会导致缓存失效，产生多个孤立克隆副本，最终反而浪费磁盘和时间。
