Composer安装VCS包卡在Cloning into是因强制git clone全量仓库，不走缓存且无视--prefer-dist；须配--prefer-source+cache-dir预缓存，或改用package类型dist包绕过。
为什么composer install VCS包会卡住
Composer 安装 git、hg 或 svn 类型的扩展包（即 VCS 包）时卡在 Cloning into... 或 Checking out...，不是因为网络慢，而是默认走 git clone 流程：初始化仓库、拉取全部历史、checkout 指定 commit —— 即使你只需要一个 tag，它也得把整个 repo 下完。尤其当包体积大、分支多、或目标 Git 服务器响应慢（如私有 GitLab 响应超时），就会明显卡顿。
- Git 包不会走 Composer 的
cache-files缓存（ZIP/tar 包才进files/），所以clear-cache对它无效 -
--prefer-dist对 VCS 包完全不生效，Composer 会无视该参数，强制走 clone - 若项目
composer.json中显式写了"type": "vcs"仓库，或依赖包的dist字段缺失/被覆盖，就一定会触发 VCS 拉取 - CI 环境中未配置 SSH key 或 HTTPS token，
git clone会卡在认证环节，日志里可能只显示“still running”
用 --prefer-source + cache-dir 预缓存 Git 仓库
核心思路是让 Composer 把 clone 下来的 Git 仓库完整存进本地缓存，下次安装同版本时直接复用工作区，跳过网络和解包开销。这需要两个条件同时满足：
- 必须设
COMPOSER_PREFER_SOURCE=1（或加--prefer-source参数），否则 Composer 不会缓存 Git 工作区 - 确保
cache-dir可写且路径稳定（如 CI 中挂载~/.composer/cache为持久卷） - VCS 包的
version必须精确匹配（如"dev-main#abc123"或"v2.1.0"），模糊版本（如"^2.1"）每次解析结果可能不同，无法命中缓存 - 缓存路径格式为：
{$cache-dir}/vcs/{url-hash}/，里面包含完整的.git/目录和 checkout 后的代码
验证是否生效：安装后检查 composer config -g cache-dir 指向的目录下是否存在 vcs/ 子目录，且其子目录非空。
离线使用 VCS 缓存的实操要点
VCS 缓存不能像 files/ 那样直接打包带走，但可以离线复用——前提是源环境与目标环境的 Git 二进制、SSH 配置、以及 Composer 版本一致。关键操作如下：
- 确认缓存已生成：在联网环境执行一次
COMPOSER_PREFER_SOURCE=1 composer install --no-dev，再检查$(composer config -g cache-dir)/vcs/是否含对应仓库目录 - 同步整个
vcs/目录到目标机相同cache-dir路径下（注意权限，尤其是.git/config中的 URL 和 credential） - 目标机必须能运行
git --version，且支持该仓库所用协议（如git@需 SSH agent 或~/.ssh/config） - 禁用网络校验：务必设置
COMPOSER_DISABLE_NETWORK=1，否则 Composer 仍会尝试 fetch origin 获取最新 commit，导致失败 - 避免插件干扰：加上
--no-plugins --no-scripts，防止某些插件（如symfony/flex）在无网时尝试访问 packagist
替代方案：改用 dist 包 + 手动注入缓存
如果 VCS 卡顿无法缓解，最稳的方式是绕过它——让包提供 dist 下载地址。多数现代包都支持，只需在 composer.json 中补全：
{
"repositories": [
{
"type": "package",
"package": {
"name": "vendor/package",
"version": "1.2.3",
"dist": {
"url": "https://example.com/package-1.2.3.zip",
"type": "zip"
},
"autoload": { "psr-4": { "Vendor\Package\": "" } }
}
}
]
}
然后手动把 ZIP 文件放进缓存：cp package-1.2.3.zip $(composer config -g cache-dir)/files/vendor/package/1.2.3.0-zip/，再运行 composer install --prefer-dist 即可跳过所有 Git 操作。
VCS 缓存本质是“带状态的 Git 工作区复用”，不是纯文件缓存；一旦目标机 Git 环境或 SSH 凭据不一致，就容易在 checkout 或 submodule 初始化阶段静默失败——这点比 dist 缓存脆弱得多，部署前务必在目标环境用 git -C $(cache-dir)/vcs/xxx/ status 实测能否正常工作。
