默认 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设置。 -
