Composer安装失败主因是GitHub API限流（404伪装或429），需通过auth.json配置GitHub Token并确保正确加载；推荐用COMPOSER_AUTH环境变量安全注入，避免全局污染与权限泄漏。
GitHub API 限流触发 404 或 429 错误时 Composer 安装失败
不登录 GitHub 的匿名请求每小时最多 60 次，GitHub Actions 默认使用无认证的 https://api.github.com，一旦项目依赖较多（尤其含私有包、频繁更新的 monorepo），composer install 很容易因 API 限流返回 404 Not Found（实际是限流伪装）或明确的 429 Too Many Requests。这不是 Composer 本身问题，而是 GitHub 强制的访问控制策略。
配置 auth.json 并在 CI 中安全注入 GitHub Token
必须让 Composer 使用带权限的 GitHub Token 访问 API，否则无法绕过限流。关键不是“加 token”，而是确保它被正确加载且不泄露：
-
auth.json必须放在COMPOSER_HOME目录下（默认是~/.composer/），不能只放项目根目录 - GitHub Action 中禁止硬编码 token 或写入仓库，应通过
secrets.GITHUB_TOKEN（自动提供）或自定义 secret 注入 - 推荐用
composer config命令动态生成，避免手动处理 JSON 格式错误
composer config --global github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
该命令会自动写入 ~/.composer/auth.json，内容类似：
{
"github-oauth": {
"github.com": "ghp_..."
}
}
确认 composer install 是否真正使用了 token
即使配置了 token，Composer 也可能因缓存、镜像源或 package 类型跳过 GitHub API。验证方法：
- 添加
-v参数运行：composer install -v，观察日志中是否出现Downloading https://api.github.com/...并附带Authorization: Bearer - 若依赖来自
packagist.org但包元数据含 GitHub 仓库（如"source": { "type": "git", "url": "https://github.com/vendor/pkg.git" }），Composer 仍会调用 GitHub API 获取 commit 信息 —— 这正是限流高发点 - 检查是否启用了
packagist.org镜像（如阿里云），它无法替代 GitHub API 调用，仅加速包下载
CI 中更稳妥的写法：避免全局污染与权限泄漏
在 GitHub Actions 中，直接用 --global 可能影响其他 job；同时，GITHUB_TOKEN 权限默认不含 packages: read，但对公开仓库的 API 访问已足够。更可控的做法是：
- 用
COMPOSER_AUTH环境变量传入 JSON 字符串（无需文件操作） - 确保
composer install在同一 step 中执行，避免跨 step 丢失环境变量 - 不要用
run: echo '{...}' > ~/.composer/auth.json，易出错且可能残留敏感信息
env:
COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GITHUB_TOKEN }}"}'
run: composer install --no-interaction
GitHub Actions 的 GITHUB_TOKEN 有效期仅限当前 workflow run，且自动过期；但很多人忽略的是：如果项目依赖了多个 GitHub 组织下的私有包，而 token 没有对应组织的 read:packages 权限，即使过了 API 限流，仍会卡在 401 —— 这类权限问题不会报限流错误，但现象相似，排查时得看具体 HTTP 状态码。 
