CI中必须用composer install而非update,因其严格按已提交的composer.lock还原全部依赖版本、顺序及嵌套关系,确保构建可重现;update会重算依赖树并生成新lock,绕过代码审查引发BC break或Fatal error。

CI里必须用composer install,绝不能用composer update——否则构建不可重现,线上行为随时漂移。
为什么composer install是CI中唯一安全选项
CI不是开发机,它不参与“选版本”的决策。composer update会重算整个依赖树、生成新composer.lock,等于绕过代码审查偷偷升级包。昨天通过的流水线,今天可能因monolog/monolog的一个 patch 版本引入 BC break 或 Fatal error: Class 'PHPUnit\Framework\TestCase' not found。
composer install则严格按已提交的composer.lock还原:版本、顺序、嵌套关系全部锁定。前提是 Git 仓库里必须有它——CI 不会帮你生成,没这个文件,命令直接报错退出。
- 常见错误现象:
Root package 'xxx' cannot be found,大概率是漏提composer.lock - 多包项目(monorepo)中,每个子包目录下都得有自己独立的
composer.lock,否则install会自动退化为update - GitLab / GitHub Actions 默认拉取 clean checkout,只靠
composer.lock启动安装
composer install必须加的三个生产参数
漏掉任一个,轻则 autoload 慢 2–3 倍,重则运行时崩溃。它们不是可选项,是生产构建的底线:
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
-
--no-dev:跳过require-dev里的包。否则phpunit、symfony/debug-bundle会打进镜像,还可能触发class_exists('PHPUnit\Framework\TestCase')这类运行时 fatal -
--optimize-autoloader(或-o):生成vendor/composer/autoload_classmap.php,把 PSR-4 映射编译成静态数组,跳过每次 class 查找时的文件系统遍历 -
--classmap-authoritative:告诉 autoloader “classmap 里没有的类,就真的不存在”,彻底禁用file_exists()探测——既提速,又防因符号链接或大小写问题误加载
正确写法:composer install --no-dev --optimize-autoloader --classmap-authoritative --no-interaction
缓存策略:该缓存vendor/还是~/.composer/cache?
两者适用场景不同,混用反而易出问题:
-
vendor/缓存适合分支稳定、依赖变动少的项目(如 GitLab CI 的cache: paths: [vendor/]),但要注意:一旦composer.lock变更,缓存失效;且 Docker 多阶段构建中不应缓存它,应由 builder 阶段生成后 COPY -
~/.composer/cache更通用,适合多项目共享,Docker 中可通过 volume 挂载复用;GitHub Actions 推荐用actions/cache@v3缓存它,key 可设为${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }} - 本地开发用
vendor/缓存没问题,但 CI 中若同时缓存vendor/和~/.composer/cache,可能因权限、UID/GID 不一致导致 autoload 加载失败
离线环境或容器内执行composer install失败怎么办
真离线(composer diagnose显示 HTTP connectivity: FAIL)时,composer install默认会卡在元数据校验环节。此时不能靠配镜像源或代理解决:
- 最稳妥方案是 Docker 多阶段构建:第一阶段用
php:8.2-cli等带网镜像,COPY composer.json composer.lock ./后执行composer install --no-dev --no-scripts --optimize-autoloader;第二阶段用精简镜像,COPY --from=builder /app/vendor /var/www/html/vendor - 务必加
--no-scripts:避免某些包的post-install-cmd触发网络请求(比如自动 fetch 前端资源) - 若需宿主机预打包
vendor/再挂载进容器,必须确保宿主机 PHP 版本、扩展、OS 与目标容器完全一致,且挂载后执行chown -R 82:82 vendor(假设容器内 www-data UID=82)
最容易被忽略的是:离线构建时,composer.lock本身必须由相同 PHP 环境生成——不同版本 PHP 可能导致autoload_static.php内容不兼容,运行时报Class not found却查不出原因。

















