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 目录，而这种问题往往要到部署阶段才会暴露，排查起来相当棘手。
