GitHub Actions 中 composer install 报错或找不到包的根本原因是工作目录未切换、composer.json 未检出、PHP 环境缺失扩展或版本不匹配、缓存策略错误及参数缺失；需用 actions/checkout@v4 后指定 working-directory 或 cd，搭配 shivammathur/setup-php@v2 显式配置 PHP 版本与扩展，缓存 ~/.composer/cache 而非 vendor/，并严格使用 --no-interaction --prefer-dist --optimize-autoloader 参数，按 job 类型选择是否加 --no-dev。
GitHub Actions 里跑 composer install 不是“配一下就能用”，而是必须显式处理工作目录、PHP 环境、缓存策略和参数组合——漏掉任一环，轻则超时失败，重则构建产物不可用。
为什么 composer install 在 CI 里总报错或找不到包？
根本不是网络问题，而是默认容器里既没切到项目根目录，也没检出 composer.json 和 composer.lock。GitHub Actions 的 runner 是干净镜像，actions/checkout@v4 后不加 cd 或 working-directory，后续所有命令都在空目录执行。
- 确认第一步是
uses: actions/checkout@v4，且没加submodules: false（如果依赖含 Git 子模块，必须设为true） - 后续步骤要么统一加
working-directory: ${{ github.workspace }}，要么在run前手动cd ${{ github.workspace }} - 检查日志开头是否输出
ls -la，确认composer.json和composer.lock真的存在
PHP 环境和 Composer 版本怎么配才不翻车？
Ubuntu runner 默认没有 composer 命令，也未必装了 ext-zip 或 ext-xml——而 composer install 一启动就校验这些扩展，缺一个就直接退出。
- 别用
sudo apt install composer：Ubuntu 官方源里的版本老旧（常是 v2.0.x），且不保证与当前 PHP 匹配 - 用
shivammathur/setup-php@v2，明确指定php-version（必须和composer.json中"php": "^8.2"一致）和extensions（至少mbstring, xml, zip, curl） - 需要固定 Composer 版本（如 v2.5.8）时，在 setup-php 的
with里加composer-version: '2.5.8' - 如果项目依赖
ext-redis或ext-sodium，必须显式写进extensions列表，否则到测试阶段才爆错
缓存 vendor/ 还是缓存 ~/.composer/cache？
缓存 vendor/ 目录看着直观，但实际容易失效、体积大、跨 OS 权限异常；真正该缓存的是 Composer 自身的下载缓存（~/.composer/cache），它复用率高、恢复快、稳定。
- 用
actions/cache@v3缓存路径设为~/.composer/cache，key 用${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }} - 不要缓存
./vendor：GitHub cache 有 10GB 限制，vendor/动辄几百 MB，还容易因 PHP 版本或扩展差异导致类加载失败 - 缓存步骤必须放在
setup-php之后、composer install之前，否则缓存不生效 - 如果用了私有 Git 仓库依赖，记得在
composer install前加一行composer config github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
composer install 参数怎么选才安全又高效？
CI 场景下，交互式提示、源码安装、未优化 autoload 都是隐患——它们会让构建卡住、变慢，甚至产生不可复现的运行时错误。
- 必加
--no-interaction --prefer-dist --optimize-autoloader：前者防卡住，后者加速下载并生成扁平化 autoload map -
--no-dev要按 job 类型分情况：构建/打包 job 必须加，测试 job 必须去掉（否则vendor/bin/phpunit不存在） - PHP 8+ 下
--optimize-autoloader效果有限，但对 PHP 7.4 仍有明显启动提速，别省 - 避免在
run步骤里写composer install，而要用php composer.phar install（确保调用的是 setup-php 安装的版本）
最易被忽略的一点：缓存 key 里只用 hashFiles('composer.lock') 还不够——如果项目支持多 PHP 版本矩阵测试，key 必须包含 ${{ matrix.php-version }}，否则不同版本共用同一份缓存，autoload 会错乱。
