应缓存~/.composer/cache而非vendor/，因其存储Git克隆快照、dist包及元数据，安全高效；需显式设COMPOSER_CACHE_DIR并匹配cache路径，key建议含PHP版本与composer.lock内容哈希。
GitLab CI里缓存Composer VCS克隆结果，到底该缓谁？
缓 vendor/ 是最常见也最危险的操作。不同分支、不同 composer.lock 哈希、不同 PHP 版本下复用同一份 vendor/，轻则 Class not found，重则测试通过但线上报错。真正该缓的是 Composer 自己的元数据与下载包缓存：~/.composer/cache。这个目录里存着 Git clone 出来的仓库快照（cache/vcs/ 子目录）、dist 包 zip、以及 packagist 元数据，复用它既安全又高效。
- 必须显式设置
COMPOSER_CACHE_DIR，GitLab 默认不设这个变量，即使你写了 cache: paths: [~/.composer/cache]，Composer 仍会往 ~/.composer/cache 写，但实际缓存路径可能因环境变量缺失而 fallback 到默认值，导致缓存未命中
- 推荐在 job 级
variables 中写：COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
-
cache: 块中的 paths 必须严格匹配该路径，不能写成 ~/.composer/cache 或 $HOME/.composer/cache
私有 VCS 仓库（GitLab/GitHub）在 CI 中反复 clone 慢？先确认认证是否生效
Composer 在 CI 中对私有 VCS 仓库的拉取失败，90% 不是缓存问题，而是认证没走通。常见现象是：本地能装，CI 报 Failed to clone https://gitlab.example.com/org/pkg.git 或静默跳过私有源。
- 如果用 HTTPS + Token，确保
auth.json 已注入 CI 环境（如通过 before_script echo 写入 $COMPOSER_CACHE_DIR/auth.json），且格式正确：
{
"gitlab.example.com": {
"token": "glpat-xxxxxx"
}
}
- 如果用 SSH，必须在 CI runner 宿主机上预置私钥，并配置
~/.ssh/config 显式指定 IdentityFile 和 StrictHostKeyChecking no；仅把公钥加到 GitLab 并不够，CI runner 还得能 ssh-agent 转发或手动 load key
- 私有仓库 URL 必须可直接
git clone：HTTPS 地址要带 token，SSH 地址要能免密登录，不能是网页 URL（如含 /tree/main）
缓存 key 怎么设才不“跨版本污染”？
VCS 类型依赖的缓存 key 若只用 $CI_COMMIT_REF_SLUG，会导致 PHP 8.1 和 8.3 的作业共用同一份 ~/.composer/cache，而 Composer 对不同 PHP 版本生成的 autoloader 或扩展兼容性检查可能不同，引发隐性错误。
- 推荐组合 key：
"${PHP_VERSION}-${sha256sum composer.lock | cut -d' ' -f1}"
-
PHP_VERSION 作为变量传入 job（例如 PHP_VERSION: "8.3"），避免硬编码
- 若项目不固定 PHP 版本，可用
$(php -v | head -1 | cut -d' ' -f2 | cut -d'.' -f1,2) 动态提取，但需确保 php 命令已就绪
- 不要用
composer.lock 文件名哈希代替内容哈希——文件存在但内容未变时，哈希不变；内容变了但文件名一样时，哈希才变
为什么加了缓存还是每次重 clone？检查这三处
即使缓存路径和 key 都对，仍出现重复 clone，大概率是以下某处断链：
-
composer install 是否加了 --no-cache？CI 脚本里容易误加，尤其从调试命令复制过来时
-
repositories 数组中是否漏写了 {"packagist.org": false}？没禁用兜底源时，Composer 在私有源未命中后仍会访问官方源（哪怕你配了阿里云镜像），此时它不会用本地 VCS 缓存，而是重新走网络
-
cache: 是否声明在正确 stage？比如写在 test: job 里，但 build: job 没配缓存，那么 build 阶段的 clone 就永远不被缓存
COMPOSER_CACHE_DIR，GitLab 默认不设这个变量，即使你写了 cache: paths: [~/.composer/cache]，Composer 仍会往 ~/.composer/cache 写，但实际缓存路径可能因环境变量缺失而 fallback 到默认值，导致缓存未命中variables 中写：COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
cache: 块中的 paths 必须严格匹配该路径，不能写成 ~/.composer/cache 或 $HOME/.composer/cache
Failed to clone https://gitlab.example.com/org/pkg.git 或静默跳过私有源。
- 如果用 HTTPS + Token，确保
auth.json已注入 CI 环境（如通过before_scriptecho 写入$COMPOSER_CACHE_DIR/auth.json），且格式正确：{ "gitlab.example.com": { "token": "glpat-xxxxxx" } } - 如果用 SSH，必须在 CI runner 宿主机上预置私钥，并配置
~/.ssh/config显式指定 IdentityFile 和 StrictHostKeyChecking no；仅把公钥加到 GitLab 并不够，CI runner 还得能 ssh-agent 转发或手动 load key - 私有仓库 URL 必须可直接
git clone：HTTPS 地址要带 token，SSH 地址要能免密登录，不能是网页 URL（如含/tree/main）
缓存 key 怎么设才不“跨版本污染”？
VCS 类型依赖的缓存 key 若只用 $CI_COMMIT_REF_SLUG，会导致 PHP 8.1 和 8.3 的作业共用同一份 ~/.composer/cache，而 Composer 对不同 PHP 版本生成的 autoloader 或扩展兼容性检查可能不同，引发隐性错误。
- 推荐组合 key：
"${PHP_VERSION}-${sha256sum composer.lock | cut -d' ' -f1}"
-
PHP_VERSION 作为变量传入 job（例如 PHP_VERSION: "8.3"），避免硬编码
- 若项目不固定 PHP 版本，可用
$(php -v | head -1 | cut -d' ' -f2 | cut -d'.' -f1,2) 动态提取，但需确保 php 命令已就绪
- 不要用
composer.lock 文件名哈希代替内容哈希——文件存在但内容未变时，哈希不变；内容变了但文件名一样时，哈希才变
为什么加了缓存还是每次重 clone？检查这三处
即使缓存路径和 key 都对，仍出现重复 clone，大概率是以下某处断链：
-
composer install 是否加了 --no-cache？CI 脚本里容易误加，尤其从调试命令复制过来时
-
repositories 数组中是否漏写了 {"packagist.org": false}？没禁用兜底源时，Composer 在私有源未命中后仍会访问官方源（哪怕你配了阿里云镜像），此时它不会用本地 VCS 缓存，而是重新走网络
-
cache: 是否声明在正确 stage？比如写在 test: job 里，但 build: job 没配缓存，那么 build 阶段的 clone 就永远不被缓存
"${PHP_VERSION}-${sha256sum composer.lock | cut -d' ' -f1}"
PHP_VERSION 作为变量传入 job（例如 PHP_VERSION: "8.3"），避免硬编码$(php -v | head -1 | cut -d' ' -f2 | cut -d'.' -f1,2) 动态提取，但需确保 php 命令已就绪composer.lock 文件名哈希代替内容哈希——文件存在但内容未变时，哈希不变；内容变了但文件名一样时，哈希才变-
composer install是否加了--no-cache？CI 脚本里容易误加，尤其从调试命令复制过来时 -
repositories数组中是否漏写了{"packagist.org": false}？没禁用兜底源时，Composer 在私有源未命中后仍会访问官方源（哪怕你配了阿里云镜像），此时它不会用本地 VCS 缓存，而是重新走网络 -
cache:是否声明在正确 stage？比如写在test:job 里，但build:job 没配缓存，那么 build 阶段的 clone 就永远不被缓存
VCS 缓存真正起效的前提，是 Composer 在解析 repositories 时，能识别出目标仓库已在 cache/vcs/ 下有完整克隆，且 commit hash 匹配。这个判断依赖于 cache 目录结构完整、认证持续有效、以及没有被 --no-cache 或兜底源绕过。任何一环松动，缓存就形同虚设。
