如何使用Composer配置持续集成CI工具

Composer不是CI工具，仅作PHP依赖管理；CI中需用composer install而非update，须加--no-interaction等参数、匹配PHP版本、配置私有包认证，并确保PHP扩展齐全以保障构建稳定可重现。

首先得明确一点：Composer本身并非CI工具，也谈不上直接“配置CI”。它的核心身份是PHP的依赖管理器。那么，为什么持续集成流程里总能看到它的身影？原因很简单——CI需要安装项目依赖、运行测试、检查代码质量，而这些任务，恰恰是通过在CI脚本里调用Composer命令来完成的。

CI 脚本里怎么正确执行 composer install

在大多数CI环境（比如GitHub Actions、GitLab CI、CircleCI）中，vendor/目录默认是不被缓存的。这就意味着每次构建都可能从头开始安装依赖，既耗时又容易因网络等问题失败。所以，关键不在于“会不会运行”这条命令，而在于如何让它跑得稳、反赌，并且结果可复现。这里有几个必须注意的细节：

• 始终加上这些参数：--no-interaction --prefer-dist --optimize-autoloader。这能避免脚本因等待交互输入而卡住，优先下载分发压缩包以提升速度，并生成优化后的自动加载映射，提升运行时性能。
• 严格匹配PHP版本：必须确保CI环境中的PHP版本与composer.json里config.platform.php的设置一致，或者与CI运行时指定的版本匹配（例如在GitHub Actions中明确使用php-version: '8.2'）。否则，composer install可能会跳过某些平台依赖不匹配的包，甚至抛出“Your lock file does not contain a compatible set of packages”这样的错误。
• 提前配置私有包认证：如果项目依赖私有仓库（如自建的GitLab或Satis），必须在CI脚本执行前，通过注入Secrets等方式配置好auth.json。缺少这一步，composer install会在认证环节直接挂起。

为什么 composer update 不该出现在 CI 主流程里

这是一个需要反复强调的原则。composer update会更新依赖版本并改写composer.lock文件，而CI的核心原则之一正是“构建可重现”——依赖版本必须被锁定，并且任何变更都应经过人工审核。在CI中自动执行更新，等同于绕过了版本控制，极易导致线上行为发生不可预知的变化。

• CI中只应使用composer install：这条命令严格读取composer.lock文件来安装依赖，确保版本一致。composer update的操作，应该仅限于本地开发环境，或者在专门用于更新依赖的分支上手动执行。
• 兼容性检查的替代方案：如果需要在CI中验证项目与更新后依赖的兼容性（例如测试多个PHP版本），可以使用composer update --dry-run进行模拟检查。这不会实际更新lock文件，但能看出是否存在可升级的版本或冲突。
• 一个典型的错误场景：误将update命令放入CI脚本，可能导致Pull Request的构建成功，但合并后新的lock文件并未被提交。下一次构建时，因为lock文件与json文件记录的版本不一致，构建便会失败。

常见 CI 错误：PHP 扩展缺失导致 composer install 失败

这个问题相当隐蔽。Composer在安装某些依赖包（例如ext-gd、ext-mbstring、ext-xml）时，会检查所需的PHP扩展是否已启用。然而，为了追求轻量，许多默认的CI镜像会精简掉这些“非核心”扩展，于是就会报出类似“The requested PHP extension gd is missing from your system”的错误。

• GitHub Actions的解决方案：在steps中，使用shivammathur/setup-php这类Action，并通过参数显式启用所需扩展，例如ext-gd: true。
• GitLab CI的解决方案：在.gitlab-ci.yml文件的before_script阶段，通过包管理器安装缺失的扩展。例如：apt-get update && apt-get install -y php-gd php-mbstring。
• 自建Runner的预防措施：确保CI Runner的PHP环境配置与本地开发环境保持一致。一个实用的技巧是，在CI脚本中加入一行诊断命令，如php -m | grep gd，可以快速确认扩展是否已加载。

说到底，在CI中集成Composer，真正的难点不在于写出那几行composer install命令，而在于让整个依赖安装链路对PHP版本、系统扩展、仓库权限、网络状况等因素都做到“无感”适配。任何一个环节没有对齐，CI就可能在最意想不到的地方停下来，并且只留下一句令人困惑的“Script failed with exit code 2”。