如何在GitLab CI/CD Pipeline中高效缓存Composer Vendor目录？

默认 cache 配置常失效，因 GitLab CI/CD 缓存键仅依赖 composer.lock 文件哈希，但 Composer 安装实际受 composer.json（如 require-dev、platform、config）和 PHP 版本共同影响；推荐用 files: [composer.lock] + prefix: "${CI_JOB_NAME}-php-${PHP_VERSION}" 确保缓存唯一性与一致性。

为什么默认的 cache 配置在 Composer 上经常失效？

GitLab CI/CD 的 cache 机制按 job 名称 + key 哈希匹配缓存，但 Composer 安装结果受 composer.json 和 composer.lock 共同影响。如果只用 files: ["composer.lock"] 作为 key，而实际安装时 composer.json 中的 require-dev 或平台配置（如 platform.php）变了，缓存仍会命中但导致 vendor 不一致或安装失败。

• 不要只依赖 composer.lock 文件哈希——它不包含平台约束、插件行为、或 config 段中影响安装路径的设置
• 避免用 untracked: true 缓存整个 vendor/ 目录——CI runner 清理时可能残留旧文件，引发 autoload 冲突
• 不同 PHP 版本下生成的 vendor/ 不可混用，必须将 PHP 版本纳入 cache key

推荐的 cache 配置写法（含 PHP 版本感知）

用 cache:key: 的 files + prefix 组合，同时锁定 composer.lock 和运行时 PHP 版本。GitLab 会自动计算文件内容哈希，并拼上前缀形成唯一 key。

cache:
  key:
    files:
      - composer.lock
    prefix: "${CI_JOB_NAME}-php-${PHP_VERSION}"
  paths:
    - vendor/

• PHP_VERSION 需在 .gitlab-ci.yml 中定义为变量，例如 PHP_VERSION: "8.2"，或从 image 标签提取（如用 php:8.2-cli 时可设为 8.2）
• 确保所有使用该缓存的 job（如 test、phpcs）都用相同 prefix 和 files，否则无法共享
• 若项目启用 composer install --no-dev，建议拆分缓存：一个用于 install（含 dev），一个用于 install --no-dev（用不同 prefix）

如何避免 vendor/ 缓存污染导致的 Class not found？

常见原因是缓存未随 autoload 变更刷新，尤其是添加/删除了 psr-4 映射或修改了 classmap。Composer 的 dump-autoload 不会触发缓存更新，但 vendor/autoload.php 本身又不在 files 列表里。

• 每次 composer install 后显式运行 composer dump-autoload --optimize，并把它加入缓存 key 的依赖检查（通过自定义脚本生成哈希）
• 更稳妥的做法：在 before_script 中加校验逻辑，比如检测 composer.json 的 autoload 段是否变更，若变更则强制清空 vendor/ 并跳过缓存恢复
• 禁止在 CI 中运行 composer update —— 它会改写 composer.lock，破坏 cache key 稳定性；应只在本地更新并提交新 lock 文件

进阶：用 artifacts 替代 cache 的适用场景

当项目有多个阶段（如 build → test → deploy），且只有最后阶段才需要完整 vendor/，前面阶段只需基础依赖时，cache 可能造成冗余传输。此时可用 artifacts 按需传递。

build:
  stage: build
  script:
    - composer install --no-interaction --prefer-dist
  artifacts:
    paths:
      - vendor/
    expire_in: 1 week
test:
stage: test
script:
vendor/bin/phpunit
needs: ["build"]

• artifacts 是跨 stage 传递的，比 cache 更精确；但不支持“增量恢复”，每次都会全量下载 vendor/
• 仅当 vendor/ 大小可控（
• 注意 artifacts:expire_in 必须显式设置，否则默认保留 30 天，占满 GitLab 存储

最易被忽略的一点：GitLab Runner 的 cache 默认使用 shared 类型（如 S3 或 Redis），但某些私有 runner 配置为 none，此时 cache 配置完全无效——务必先确认 runner 的 cache_type 设置。