Composer清理缓存对VCS超时无效,因其不删除~/.composer/cache/vcs/下残留的裸仓库;必须手动清除vcs缓存、禁用VCS回退(--prefer-dist)、配置dist字段并使用--no-cache强制走ZIP安装。

不是缓存问题,而是 Composer 在 VCS 模式下反复尝试失败的 Git 克隆,且默认不放弃重试 —— 清缓存只能治标,必须同步禁用 VCS 回退、改用 dist、并清理残留裸仓库。
为什么 composer clear-cache 对 VCS 超时无效?
VCS 超时(如 Cloning into '/tmp/xxx'... fatal: unable to access 'https://gitlab.example.com/group/repo.git/': Failed to connect to gitlab.example.com port 443 after 75000 ms: Connection refused)根本不在 clear-cache 的清理范围内。它只删 ~/.composer/cache/files/ 和 repo/,而 Git 克隆失败产生的临时裸仓库、失败日志、甚至部分已写入一半的 vcs/ 缓存,都会被跳过。
-
clear-cache不碰~/.composer/cache/vcs/下的裸仓库目录(哪怕克隆中途失败,也会留下gitlab.example.com/group-repo.git/这类目录) - Composer 默认启用
"preferred-install": "auto",遇到私有库会优先走 VCS(git clone),而非 dist(zip);一旦 VCS 失败,它不会自动 fallback,而是卡住或重试直到超时 - 某些 GitLab 实例返回 403 或 429 后,Composer 仍会复用旧的认证凭据(如过期 token)尝试连接,导致“清了缓存还是连不上”
必须手动清理 vcs/ 并强制走 dist
先定位并删除所有与目标私有库相关的裸仓库缓存,再强制让 Composer 放弃 VCS、改用 ZIP 分发包:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 查缓存路径:
composer config --global cache-dir(Linux/macOS 是~/.composer/cache,Windows 是$env:APPDATA\Composer\Cache) - 进
vcs/目录,按域名或项目名模糊删:rm -rf ~/.composer/cache/vcs/gitlab.example.com*(PowerShell 用Remove-Item -Recurse -Force "$env:APPDATA\Composer\Cache\vcs\gitlab.example.com*") - 在项目
composer.json中显式禁用 VCS 回退:添加"prefer-stable": true和"minimum-stability": "stable",并确保私有包的composer.json里定义了"dist"字段(如{"url": "https://gitlab.example.com/group/repo/-/archive/v1.2.3/repo-v1.2.3.zip", "type": "zip"}) - 安装时加
--prefer-dist --no-cache:跳过 VCS 尝试,直取 dist URL,且不复用本地 ZIP 缓存
Git 认证失效导致的假性超时怎么识别?
表面是连接超时,实际是认证失败后被服务器拒绝(比如 token 过期、IP 被限流、OAuth scope 不足),但 Git 协议返回错误太笼统,容易误判为网络问题:
- 运行
composer update -v,盯住日志里类似Executing command (CWD): git clone --mirror 'https://gitlab.example.com/group/repo.git' '/home/user/.composer/cache/vcs/https---gitlab.example.com-group-repo.git/'这一行之后是否紧跟着Cloning into bare repository...—— 如果没有,大概率是认证卡在 HTTP 层 - 手动测试 Git 访问:
curl -I -H "Authorization: Bearer xxx" https://gitlab.example.com/api/v4/projects/group%2Frepo(把xxx替换为你配置的 token),看是否返回200 OK - 检查 token 权限:GitLab 需要
read_api+read_repository;GitHub 需要reposcope。少一个,就会静默失败
部署环境里 VCS 超时更难排查?注意这三点
CI/CD 流水线中,VCS 超时往往叠加权限、沙盒、DNS 等多层干扰,不能只靠清缓存:
- 确认
COMPOSER_CACHE_DIR已导出且路径可写(尤其 Docker 容器内挂载缓存卷时,常因 UID 不匹配导致vcs/目录创建失败却无报错) - 禁用 SSH:CI 环境极少配 SSH key,但 Composer 可能因
git@URL 自动 fallback 到 SSH,直接卡死;统一用 HTTPS + token,并在composer.json的repositories中明确写"type": "vcs"和完整 HTTPS URL - 加 DNS 缓存预热:某些镜像基础镜像(如
php:8.2-cli-slim)DNS 解析慢,可在composer install前加getent hosts gitlab.example.com || true强制触发解析
真正卡住 VCS 的从来不是缓存本身,而是 Composer 在失败后不主动降级、不清晰暴露认证状态、也不区分“网络不通”和“认证失败”。删 vcs/ 是必要动作,但关键是要让它别再试 Git clone —— 所以 --prefer-dist 和正确的 dist 配置,比任何缓存清理都管用。

















