根本原因是工作目录错误、未检出代码或未配置PHP环境；需先用actions/checkout@v4检出，再用shivammathur/setup-php@v2配置PHP+Composer，最后运行composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader。

GitHub Actions 中 composer install 报错 “Could not fetch packages” 或 “No composer.lock”

根本原因通常是工作目录不对，或没先检出代码、没设置 PHP 环境。GitHub Actions 默认不自动执行 git checkout，且 composer 需要 composer.lock 文件才能确定依赖版本——没有它，install 会失败（除非加 --no-lock，但不推荐）。

• 确保 workflow 第一步是 actions/checkout@v4
• 用 shivammathur/setup-php@v2 或 php-actions/composer@v6 设置 PHP + Composer，别只靠系统自带 PHP（可能没装 Composer 或版本太旧）
• 运行 composer install --no-interaction --prefer-dist --optimize-autoloader：其中 --no-interaction 防止卡住，--prefer-dist 加速下载，--optimize-autoloader 生成高效 autoloader（CI 场景必需）

如何跳过 dev 依赖只安装生产环境依赖？

CI 构建通常不需要 phpunit、phpcs 这类开发依赖，省掉它们能显著缩短构建时间、减小缓存体积。

• 用 composer install --no-dev --no-interaction
• 注意：如果项目里有脚本（如 post-install-cmd）依赖 dev 包，可能报错；此时需检查 composer.json 的 scripts 段，把 dev-only 逻辑挪到 require-dev 对应的条件判断里
• GitHub Actions 缓存 vendor/ 时，务必区分 --no-dev 和带 dev 的缓存键，否则混用会导致运行时找不到类

缓存 vendor/ 目录提速，但为什么每次还是重装？

常见原因是缓存 key 没随 composer.lock 内容变化而更新，导致命中了旧缓存，但 lock 文件已变，结果 vendor 不匹配。

• 正确做法：用 hashFiles('composer.lock') 作为缓存 key 的一部分，例如：
  composer-${{ hashFiles('composer.lock') }}-${{ matrix.php-version }}
• 缓存路径必须写全：不是 vendor，而是 ./vendor（相对路径）或 ${{ github.workspace }}/vendor
• 不要在缓存后加 composer install —— 应该先 restore 缓存，再判断是否命中；未命中才 install，否则跳过

steps:
  - uses: actions/cache@v4
    with:
      path: ./vendor
      key: composer-${{ hashFiles('composer.lock') }}-${{ matrix.php-version }}
  - name: Install dependencies
    run: composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
    if: steps.cache.outputs.cache-hit != 'true'

私有 GitHub 仓库依赖无法认证怎么办？

当 composer.json 引用了组织内私有 repo（如 "myorg/private-package": "dev-main"），Composer 默认无权拉取，会卡在 Cloning into '/tmp/...'... 或报 401 Unauthorized。

• 在 workflow 中配置 GITHUB_TOKEN 为 Composer 的 GitHub OAuth token：
  composer config -g github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
• 确保 composer.json 中该私有包的 type 是 vcs，且 url 用 HTTPS 格式（不是 git@…）
• 如果用的是 GitHub App token 或 PAT，权限需勾选 packages:read 和 repository:read；GITHUB_TOKEN 默认具备这些权限，优先用它

实际跑通的关键，往往卡在缓存 key 是否真唯一、GITHUB_TOKEN 是否传给了 Composer、以及 --no-dev 是否和项目脚本兼容——这三处不细看日志很难定位。