根本原因是GitLab CI未设置COMPOSER_CACHE_DIR环境变量,导致Composer无法读写声明的~/.composer/cache路径;必须显式export该变量并mkdir -p ~/.composer才能使VCS缓存生效。

GitLab CI 中 Composer 的 VCS 仓库(如私有 GitLab 项目)拉取慢,根本原因不是网络,而是缓存没生效或配置错位。 即使你加了 cache 块、写了 ~/.composer/cache 路径,composer install 仍反复 clone 私有仓库——这说明缓存没被 Composer 实际使用。
为什么 ~/.composer/cache 缓存不生效?
GitLab CI 默认不设置 COMPOSER_CACHE_DIR 环境变量。Composer 会无视你声明的缓存路径,坚持往默认位置(~/.composer/cache)写,但 CI job 是全新容器,~/.composer 每次都是空的。更关键的是:即使你用 cache: 声明了该路径,若没显式告诉 Composer「请用这个目录」,它就不会读/写它。
- 必须在
before_script或环境变量中设置COMPOSER_CACHE_DIR=~/.composer/cache - 仅靠
cache: paths: - ~/.composer/cache不够,这是 GitLab 的缓存声明,不是 Composer 的运行时配置 - CI job 启动时
~/.composer目录不存在,Composer 不会自动创建父目录,导致缓存写入失败(静默) - 验证是否生效:在
script中加ls -la ~/.composer/cache和composer config --global cache-dir
如何让 vcs 类型私有包真正走缓存?
VCS 仓库("type": "vcs")的缓存行为和普通包不同:Composer 不缓存 clone 出来的整个仓库,而是缓存 dist 归档(zip/tar.gz)。它会在首次 clone 后,自动打包成 dist 并存进 COMPOSER_CACHE_DIR/vcs/ 下。后续安装只要 hash 匹配,就跳过 clone,直接解压 dist。
- 确保私有 GitLab 仓库启用了
archive功能(默认开启;若禁用,composer install会 fallback 到 clone,无法利用 dist 缓存) - Git tag 必须规范(如
v1.2.0),否则 Composer 不生成 dist,每次重 clone - 避免在
composer.json的require中写"dev-main"这类分支别名——它强制走 clone 模式,绕过所有 dist 缓存 - CI 中建议统一用语义化版本(
"^1.2")+ 正确 tag,而不是分支名
GitLab CI 配置示例与易错点
以下片段能真正启用 VCS 缓存,且适配私有 GitLab:
使用 GitHub REST API v3 /actions/runs 和 /actions/jobs 端点诊断失败的 GitHub Actions 工作流程。解析步骤日志,识别 YAML 语法错误,并为运行器环境问题提供修复建议。
cache:
key: ${PHP_VERSION}-composer-${CI_COMMIT_REF_SLUG}
paths:
- ~/.composer/cache
<p>before_script:</p><ul><li>mkdir -p ~/.composer</li><li>export COMPOSER_CACHE_DIR=~/.composer/cache</li><li>composer config --global cache-dir $COMPOSER_CACHE_DIR</li></ul><p>script:</p><ul><li>composer install --no-interaction --no-progress --no-dev-
key中含${CI_COMMIT_REF_SLUG}可隔离 feature 分支缓存,避免 dev 分支污染 main 的 dist 缓存 - 漏掉
mkdir -p ~/.composer会导致 Composer 初始化失败,export无效 - 不要在
script里用composer config --global—— 它写入的是~/.composer/config.json,而该文件不在缓存路径内,下次 job 丢失 - 如果私有仓库需 Token 认证,用
COMPOSER_AUTH环境变量注入 JSON,而非挂载auth.json(挂载失败时无提示)
真正卡住构建速度的,往往不是网络延迟,而是缓存路径和 Composer 运行时配置之间的那层错位。VCS 缓存生效的前提,是 Composer 明确知道自己该读写哪块磁盘——而这一步,GitLab 的 cache: 声明永远替代不了 COMPOSER_CACHE_DIR 环境变量的实际赋值。

















