Jenkins 中 composer install 失败主因是环境不一致：HOME 未设、auth.json 路径错误、PHP 版本/内存不足、缓存语义不清及权限问题；需显式指定 --auth-file、--no-interaction、--optimize-autoloader，设置 memory_limit，校验缓存 key 含 lock 哈希，并修复 vendor 权限。
composer install 在 Jenkins 构建失败的常见原因
绝大多数 Jenkins 里 composer install 报错，不是因为命令写错了，而是环境不一致：Jenkins 跑在无交互、无家目录、无全局配置的用户（比如 jenkins）下，导致 composer 找不到 auth.json、读不到 ~/.composer/auth.json、甚至因缺少 HOME 环境变量直接崩溃。
- 检查 Jenkins agent 的
HOME是否设置（echo $HOME），没输出就手动设：export HOME=/var/lib/jenkins - 私有包认证别依赖全局
auth.json，改用项目级auth.json并chmod 600，再在 Jenkinsfile 中显式指定：composer install --auth-file=./auth.json - 避免用
composer global require—— Jenkins 不共享全局 vendor，且不同 job 可能冲突
Jenkins Pipeline 中安全执行 composer 的最小配置
别在 sh 步骤里裸写 composer install。PHP 版本、内存限制、插件加载都可能让构建非预期失败。
- 强制指定 PHP CLI 路径，避免系统默认 PHP 版本太低：
php /usr/local/bin/composer install - 加
--no-interaction --no-progress --optimize-autoloader --no-dev：省掉交互提示、隐藏进度条、生成高效 autoloader、跳过 dev 依赖（生产部署必须） - 内存不足时
Allowed memory size exhausted很常见，提前加大限制：php -d memory_limit=2G /usr/local/bin/composer install ... - 如果项目用了
composer-plugin-api或自定义脚本，确认 Jenkins 所用 PHP 版本满足插件要求（例如 v2 插件不兼容 PHP 7.4）
缓存 vendor 目录提升 Jenkins 构建速度
每次从零 composer install 太慢，但盲目用 cache 指令容易因 composer.lock 变更或平台差异导致 vendor 不一致。
- 只缓存
vendor/，不缓存composer.lock或composer.json—— 它们才是真实依赖源 - 缓存 key 必须包含
composer.lock的哈希值，否则 lock 更新后仍用旧缓存：key: 'composer-vendor-${env.BUILD_ID}-${sh(returnStdout: true, script: "sha256sum composer.lock | cut -d' ' -f1").trim()}' - 缓存命中后仍要运行
composer install --dry-run验证一致性，失败则清缓存重装
composer 自动化部署中容易被忽略的权限和清理环节
部署完 vendor，不代表能跑起来。Jenkins 用 jenkins 用户生成的文件，默认 web server（如 nginx + www-data）很可能没读取权限；残留的开发文件（.git、tests/）也可能意外暴露。
- 部署后立刻修复权限：
find vendor/ -type d -exec chmod 755 {} \; && find vendor/ -type f -exec chmod 644 {} \; - 删掉所有非运行必需内容：
rm -rf vendor/bin/ vendor/composer/ .git/ tests/ docs/ README.md - 别用
composer dump-autoload --optimize替代--optimize-autoloader—— 前者只优化已存在类映射，后者会在 install 阶段重建完整映射，更可靠
真正麻烦的从来不是命令怎么写，而是 Jenkins 用户看不到的环境状态、权限边界和缓存语义。每加一行 composer 相关指令，都要问一句：它在 Jenkins 的 $HOME 下能访问什么？执行用户有没有对应权限？上一次缓存是不是基于同一个 lock 文件？
