如何在GitHub Actions中配置并使用Composer？

本文共计1078个文字，预计阅读时间需要5分钟。

GitHub Actions 中直接运行 `composer install` 必然失败，因为默认环境没有安装 PHP 和 Composer。显式安装 PHP、启用扩展、配置缓存、传递参数——任何环节数据都可能卡在错误、超时或静默默认输出错误。

为什么 composer install 在 CI 里总报 “Command not found”

GitHub Actions 的 ubuntu-latest runner 不预装 PHP，更不会自带 composer 命令。写 run: composer install 就像让一辆没油的车启动——根本点不着火。

• 别用 apt install composer：Ubuntu 官方源里的版本老旧（常是 2.0.x），且不保证和当前 PHP 扩展兼容
• 别手写 curl -sS https://getcomposer.org/installer | php：绕过缓存、无法指定版本、易被网络中断打断
• 推荐用 shivammathur/setup-php@v2：它自动装对应 PHP 版本 + 最新稳定版 Composer + 指定扩展，一步到位
• 如果必须锁 Composer 版本（比如要 v2.5.8），加参数 composer-version: '2.5.8'

composer install 报 “Your requirements could not be resolved” 怎么办

这通常不是依赖写错了，而是 CI 环境和本地不一致，导致 Composer 解析出不同版本。关键在 platform 配置和 composer.lock 状态。

• 确保项目根目录有已提交的 composer.lock 文件；没有它，CI 会重新 resolve，结果不可控
• 在 composer.json 的 config.platform 里声明目标 PHP 版本，例如："php": "8.2.10" —— 这样即使 CI 跑的是 8.2.12，Composer 也按 8.2.10 解析
• 检查 setup-php 的 extensions 是否覆盖项目所需：Laravel 至少要 mbstring, xml, zip, pdo, curl；用 ext-pdo_mysql 就得加上 pdo_mysql
• 如果项目 require ext-sodium 或 ext-redis，它们也得列进 extensions，否则 composer install 会直接退出

缓存 vendor 目录反而让 CI 更不稳定？

缓存 vendor/ 看起来快，但实际极易污染：PHP 小版本升级、扩展开关变化、甚至 Composer 版本更新，都会让缓存的 vendor/ 产生二进制不兼容。官方明确建议缓存 ~/.composer/cache，而不是 vendor/。

• 必须同时缓存两层：~/.composer/cache（下载解压层） + vendor/（软链接层），缺一不可
• 缓存 key 必须含：${{ hashFiles('**/composer.lock') }} + ${{ matrix.php-version }} + ${{ hashFiles('~/.composer/composer.json') }}；硬编码 ubuntu-latest 或漏 composer.json 都会导致失效
• composer install 前必须加 --no-interaction --prefer-dist --optimize-autoloader；不加 --no-interaction 可能卡在信任仓库提示上超时
• 私有包（如 GitHub Packages）需提前配置凭证：composer config github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}

安装完 vendor/ 还跑不起来测试？

composer install 成功 ≠ 项目能运行。常见断点在 autoloader 生成失败、dev 依赖误装、或 autoload-dev 配置错误。

• 加 --optimize-autoloader 后检查是否生成了 vendor/autoload_classmap.php；没有说明 autoloader 没生效
• 除非真要跑 PHPUnit 或 PHPCS，否则别加 --dev；require-dev 里的包可能带脚本或扩展依赖，CI 里装了反而增加失败面
• 最后加一步 composer validate --strict，验证 composer.json 格式、字段引用、仓库配置是否合法
• 如果测试阶段才爆 Class not found，优先检查 autoload 和 autoload-dev 的 psr-4 映射路径是否拼错或没加 ./ 前缀

最易被忽略的是：缓存 key 里没包含 composer.json 的哈希，而你改了 config.platform 或加了新 repo，结果缓存还命中旧内容，CI 表面成功实则依赖错配。这种问题往往要等部署后才暴露，排查成本极高。