根本原因是工作目录错误、未检出代码或未配置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 是否和项目脚本兼容——这三处不细看日志很难定位。
