推荐缓存Composer下载层（~/.composer/cache）而非vendor/目录，因后者易导致跨环境不一致；缓存键须包含composer.lock哈希、PHP版本及Composer版本以确保准确性。
CI中直接缓存vendor/目录通常不推荐
因为composer install本身依赖composer.lock的精确性，而vendor/目录内容受PHP版本、扩展启用状态、平台配置（如platform）、甚至composer.json中config.platform影响。缓存整个vendor/容易在跨环境（如本地PHP 8.2 → CI PHP 8.1）或平台变更后导致“能跑但不对”的隐性问题，比如加载了为错误架构编译的扩展或跳过应触发的post-install-cmd脚本。
更稳妥的做法是缓存Composer的下载层（即~/.composer/cache），让composer install复用已下载的包归档和元数据，既提速又保一致性。
GitHub Actions中正确缓存Composer下载缓存
使用actions/cache@v4缓存~/.composer/cache，关键在于缓存键（key）必须包含：composer.lock哈希 + PHP版本 + Composer版本。否则缓存可能错配。
- 用
hashFiles('**/composer.lock')确保lock文件变更时自动失效缓存 - 用
${{ matrix.php-version }}区分不同PHP环境 - 用
composer --version输出哈希（避免因Composer小版本升级导致解析行为差异） - 缓存路径写
~/.composer/cache，不是vendor/
示例片段：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
steps:
- uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-version }}
- name: Cache Composer dependencies
uses: actions/cache@v4
with:
path: ~/.composer/cache
key: composer-${{ hashFiles('**/composer.lock') }}-${{ matrix.php-version }}-${{ hashFiles('**/composer.phar') }}
- name: Install dependencies
run: composer install --no-interaction --prefer-dist --optimize-autoloaderGitLab CI中复用Composer缓存需显式配置COMPOSER_CACHE_DIR
GitLab默认不设置COMPOSER_CACHE_DIR，即使你用cache:声明了路径，Composer仍会写入默认位置（~/.composer/cache），导致缓存未命中。必须显式覆盖。
- 在
before_script或作业级variables中设COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache" -
cache:块中路径必须与之完全一致 - 缓存键建议含
$CI_COMMIT_REF_SLUG和composer.lock校验和（可用sha256sum composer.lock | cut -d' ' -f1） - 避免用
composer update进CI——它会改composer.lock，破坏缓存稳定性
否则你会看到Downloading ...重复出现，缓存形同虚设。
私有包场景下额外注意认证与缓存隔离
如果项目依赖私有Git仓库或Packagist私有实例，缓存本身不保存认证凭据，但composer install首次运行时若因认证失败退出，后续缓存恢复也无法跳过该步骤。
- 在CI中预置
auth.json（如GitHub Actions用setup-php的extensions参数配合COMPOSER_AUTH变量） - 确保
auth.json内容不硬编码在代码中，而是通过CI secrets 注入 - 私有包的元数据（如
packages.json）也走缓存，但若认证失败，Composer会跳过该仓库索引，导致“找不到包”错误，而非缓存失效 - 不同分支/环境若用不同私有源，缓存键必须区分，否则可能混用不兼容的包索引
缓存不是万能胶，它是对确定性流程的加速；一旦涉及动态凭据、多平台适配或私有源策略，就得靠键设计和前置条件兜底。漏掉任何一个变量，就可能让CI快得莫名其妙，也错得莫名其妙。
