根本原因是runner环境干净、缓存未正确配置、PHP环境不一致；必须提交composer.lock、只缓存$HOME/.composer/cache、确保PHP版本与扩展一致、正确配置私有包认证及repositories。
GitLab CI 里 composer install 慢、失败、vendor/ 总重装，不是 Composer 有问题，而是环境没对齐、缓存配错了、composer.lock 没管好。
为什么 composer install 在 CI 里总退化成 update
根本原因是 composer.lock 没提交到仓库，或内容与 composer.json 不匹配。CI 拉下来的代码里没有 composer.lock，composer install 就会自动 fallback 到 update，重新解析依赖树，导致构建不可重现。
- 检查 Git 仓库根目录是否存在
composer.lock文件——它必须被git add并git commit - 多包项目（monorepo）中，每个子包目录下都得有自己独立的
composer.lock - CI 开头加
composer validate --strict，能立刻暴露json和lock冲突 - 别在
.gitlab-ci.yml里写composer require或create-project，这些命令会改锁文件，破坏一致性
cache 该缓什么？为什么不能缓 vendor/
缓存 vendor/ 是最常见也最危险的直觉错误。它和 PHP 版本、扩展开关（如 opcache.enable）、大小写敏感度强耦合，混用会导致 Cannot declare class 或随机 Class not found。
- 真正该缓的是
$HOME/.composer/cache，它只存 ZIP 包、git 快照和元数据，与运行环境完全解耦 - GitLab CI 的
cache配置中，paths必须只写~/.composer/cache，别加vendor/ - key 推荐用
"${CI_PROJECT_ID}-composer-${CI_COMMIT_REF_SLUG}-${CI_JOB_NAME}"，避免分支间污染 - 加一条
restore-keys: ["${CI_PROJECT_ID}-composer-main-"]，让 feature 分支冷启时能 fallback 到 main 缓存
私有包拉不下来？认证和仓库声明缺一不可
报错 Project not found or you don't have access，90% 是认证没走通，不是网络问题。
- 用 HTTPS 方式拉私有包，必须在 job 中生成
auth.json：echo "$COMPOSER_AUTH_JSON" > auth.json，变量值是 masked 的合法 JSON 字符串 -
repositories字段必须显式声明，类型为vcs，url要带.git后缀（如https://gitlab.example.com/group/pkg.git） - 如果用 SSH，除了配置
SSH_PRIVATE_KEY环境变量，还必须去每个被依赖的私有仓库页面，在 “Privately accessible deploy keys” 列表中手动启用该 key - 执行
composer install时显式指定--auth-file=auth.json --no-interaction
PHP 环境不一致导致静默失败
错误可能不报错，但运行时才崩：比如 Class 'Foo' not found，实际是某个包因 PHP 版本或扩展缺失被跳过安装。
- CI 镜像必须和本地、生产严格一致，例如都用
php:8.2-cli，别混用php:8.2-apache（后者默认不装mbstring、zip） - CI job 开头加两行校验：
php -v和php -m | grep -E "^(mbstring|xml|zip|pdo|openssl)$" - 删掉
composer.json中的"platform"配置项——它会欺骗 Composer，但运行时环境真没扩展，就直接 fatal - 内存不足时
composer install可能被 kill，开头加export COMPOSER_MEMORY_LIMIT=-1
最关键的细节是：缓存 ~/.composer/cache 只是加速下载，composer install 这一步永远不能跳。它才是校验 lock 完整性、触发 post-install-cmd、生成正确 autoloader 的唯一环节。
