GitHub Actions 中加速 composer install 必须同时缓存 ~/.composer/cache 和 vendor/，且缓存 key 需包含 PHP 版本与 composer.lock 哈希；仅缓存 vendor 会导致重复下载或二进制不兼容错误。
直接说结论：GitHub Actions 里想让 composer install 快，不能只靠“缓存 vendor”，必须同时缓存 ~/.composer/cache 和 vendor/，且缓存 key 必须包含 PHP 版本和 composer.lock 哈希——漏掉任一条件，缓存大概率失效或静默出错。
为什么只缓存 vendor/ 会变慢甚至出错
很多人看到“缓存 vendor 目录”就直接写 path: ./vendor，结果发现 CI 时间没降多少，甚至偶尔报 Class not found。这是因为：
-
vendor/里存的是软链接或解压后的文件，但 ZIP 包本身还在~/.composer/cache里；只缓vendor/，下次composer install仍要重下全部 .zip - PHP 小版本升级（如 8.2.10 → 8.2.12）或扩展开关变化时，已缓存的
vendor/可能二进制不兼容，但缓存 key 没变，CI 就直接用了——运行时报错才暴露 -
composer.json里若含"platform": {"php": "8.2"}，而缓存是用 8.1 跑出来的，autoloader 就可能生成错
缓存 ~/.composer/cache 的关键配置
这个目录缓存的是下载解压层，跳过网络拉取最省时间。但容易踩坑：
- 必须显式设置
COMPOSER_CACHE_DIR环境变量，且值要和actions/cache@v4的path完全一致，否则 Composer 仍用默认路径，缓存白配 - 缓存 key 必须含
${{ matrix.php-version }}，否则 PHP 8.1 和 8.2 共用同一份缓存，解压出来的包可能不兼容 - 如果项目依赖私有 Git 仓库，缓存命中后
composer install可能卡在Cloning into '/tmp/composer-cache/vcs/xxx'—— 因为没配 Git 凭据，得加一步：git config --global url."https://oauth2:${{ secrets.PAT }}@github.com/".insteadOf "https://github.com/"
composer install 命令必须带的参数
哪怕缓存全对，composer install 缺参数也会降级成全量安装或交互卡住：
-
--no-interaction：避免等待输入（CI 没 stdin），否则步骤挂起超时 -
--prefer-dist：强制走 ZIP 包而非 Git clone，配合~/.composer/cache才真正省时 -
--optimize-autoloader：生成扁平化 autoloader，提升后续 PHP 执行效率；不加的话，缓存虽生效，但 runtime 性能差 - CI 环境一般不需要 dev 依赖，加
--no-dev可进一步缩短时间（尤其 Laravel 项目）
缓存 key 冲突和 restore-keys 的实际作用
你看到 Cache not found for input keys 不代表失败，但若每次都出现，说明缓存从未成功写入或 key 设计不合理：
- 确保
hashFiles('**/composer.lock')写在actions/cache步骤里，而不是硬编码字符串——lock 文件一改，key 自动变，旧缓存自动失效 - 可加
restore-keys做兜底，比如：restore-keys: ${{ runner.os }}-php-${{ matrix.php-version }}-composer-，当 lock 哈希不匹配时，尝试匹配更宽泛的 key（如上一次的 PHP 版本缓存） - 不要用
**/composer.json当 key 主体——它常含 dev 依赖、scripts 等无关字段，导致无意义的 key 变动
最易被忽略的一点：缓存动作（actions/cache@v4）必须放在 shivammathur/setup-php@v2 之后、composer install 之前，且中间不能执行任何可能修改 ~/.composer/cache 或 vendor/ 的命令——顺序错，缓存就断链。
