Composer如何在GitHub Actions中用_Composer GitHub Actions教程【最新】

GitHub Actions 中需用 setup-php + php-actions/composer 组合安装 Composer，因 ubuntu-latest 默认不含 Composer；前者装 PHP 及扩展，后者按需下载指定版本二进制、校验配置并自动注入 PATH，避免 apt 安装版本陈旧或扩展缺失问题。

在 GitHub Actions 里直接敲入 composer install 命令，十有八九会收获一个冷冰冰的 Command not found 错误。原因很简单：官方提供的 ubuntu-latest 运行器镜像，默认并没有预装 Composer。这时候，可别想着用一句 apt install composer 就能蒙混过关。

为什么 setup-php + php-actions/composer 是当前最稳组合

先说结论：这套组合拳是目前公认最稳妥的方案。其背后的逻辑分工明确：GitHub 官方的 shivammathur/setup-php@v2 动作，职责是为你准备好指定版本的 PHP 运行时和所需扩展，但它“管杀不管埋”——不包含 Composer。而 php-actions/composer@v6 则是专为 CI/CD 环境设计的 Composer 执行器。它的聪明之处在于，会动态下载与你 PHP 版本匹配的 Composer 二进制文件，跳过全局安装的繁琐步骤，自动校验 composer.json 格式，并且允许你精确指定 Composer 版本（比如 composer-version: '2.5.8'）。

相比之下，手动用 curl 安装或者依赖系统的 apt 包管理器，坑就多了：Ubuntu 仓库里的 Composer 版本往往停留在陈旧的 2.0.x，而且无法保证所需的 PHP 扩展（如 ext-zip）已就位，甚至可能与你的 PHP 小版本不兼容。

• 切记：不要在 run 步骤里写 sudo apt install composer。这不仅是版本滞后的问题，更可能因扩展缺失导致后续步骤失败。
• 如果你的项目锁定了 Composer 版本（例如 v2.5.8），务必通过 composer-version 参数显式指定。否则，它会默认使用最新稳定版，而新版本可能包含破坏性变更。
• php-actions/composer 的设计很巧妙，它不依赖系统 PATH，而是将二进制文件放置在 ./bin/composer 并自动注入环境变量，完美避免了潜在的路径冲突问题。

PHP 扩展和版本必须和 composer.json 对齐

很多时候，问题不在于 Composer 本身装不上，而是 composer install 执行时，突然抛出 Your requirements could not be resolved 或提示 ext-mbstring missing。这背后的元凶往往是 PHP 环境配置不匹配。setup-php 动作默认只安装 PHP 核心，不启用任何扩展。然而，像 Lara vel、Symfony 这类主流框架，其依赖包通常硬性要求 mbstring、xml、zip、pdo 等扩展。

• 扩展列表必须手动列全：在配置 setup-php 时，extensions 参数需要明确写出所有必需的扩展，例如：mbstring, xml, zip, pdo, pdo_mysql, curl。
• PHP 版本必须严格一致：php-version 的设定，必须与 composer.json 中 "php": "^8.1" 这样的版本约束兼容。否则，Composer 的依赖解析器在第一步就会拒绝工作。
• 提前规划测试依赖：如果项目测试阶段需要用到 ext-redis 或 ext-sodium 这类扩展，也务必一并加入列表。否则，你的 CI 流程可能会在安装阶段成功，却在运行测试时突然崩溃，白白浪费一轮构建时间。

缓存 vendor 和 ~/.composer/cache 必须同时做

优化 CI 速度，缓存是关键。但这里有个常见的误区：只缓存 vendor/ 目录，下次运行时 Composer 仍然需要重新下载所有的依赖包（ZIP 文件）；反过来，如果只缓存 ~/.composer/cache（Composer 的包缓存目录），那么每次还是需要重新解压、链接到 vendor/ 目录。这两者相辅相成，缺一不可，否则提速效果将大打折扣。

• 缓存 Key 的学问：缓存 key 的设计必须足够精确。一个推荐的模式是包含操作系统、PHP 版本以及依赖锁文件的哈希值，例如：composer-${{ runner.os }}-php-${{ matrix.php-version }}-${{ hashFiles('**/composer.lock') }}-${{ hashFiles('**/composer.json') }}。这能确保环境或依赖变更时，自动生成新缓存。
• 在 Windows runner 上缓存失败？这通常是路径分隔符（反斜杠）或文件权限导致的问题。一个务实的建议是：优先考虑使用 Linux runner。
• 私有仓库的认证：如果你的项目依赖私有 Git 仓库，必须在运行 Composer 前配置好认证令牌，例如：composer config github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}。否则，即使缓存命中，也会在尝试下载私有包时因认证失败而中断。

composer install 参数不能少，尤其 --no-dev

在 CI 环境中，我们通常不需要安装 require-dev 部分定义的开发依赖（比如 PHPUnit、静态分析工具）。漏掉 --no-dev 参数，后果不仅仅是安装时间增加 30% 到 60%，还会导致缓存体积膨胀，甚至可能因为开发依赖包的版本冲突，引发自动加载错误。

• 核心参数组合：建议使用这套参数组合：--no-interaction --prefer-dist --optimize-autoloader --no-dev。
• --no-interaction 能防止某些 Composer 插件弹出交互式提示，导致流程挂起。
• --prefer-dist 强制 Composer 下载打包好的 ZIP 分发版，而不是进行 Git clone，这通常更稳定、更快速。
• 安装后验证：一个被低估的好习惯是，在安装完成后，用一条简单的命令验证自动加载文件是否有效：php -d display_errors=Off -d error_reporting=0 -f vendor/autoload.php。这能提前发现潜在的语法错误，避免出现“安装成功，测试却跑不起来”的尴尬局面。

最后，还有一个极其隐蔽的陷阱：PHP 小版本对二进制扩展（PECL 扩展）的影响。例如，为 PHP 8.1 编译的 ext-protobufmatrix.php-version。如果遗漏，可能导致不同 PHP 版本的构建共享了被污染的 vendor 目录，而这种问题往往要到部署阶段才会暴露，排查起来相当棘手。