github actions 中直接运行 composer install 必定失败，因默认环境既无 php 也无 composer；必须用 shivammathur/setup-php 显式安装匹配版本的 php 与 composer、启用必要扩展、缓存 ~/.composer/cache 和 vendor/、添加 --no-interaction --prefer-dist --optimize-autoloader 参数，并确保 composer.lock 存在且缓存 key 包含其哈希及 php 版本。
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 表面成功实则依赖错配。这种问题往往要等部署后才暴露，排查成本极高。
