解决Composer使用过程中因GitHub API限流导致的依赖安装失败问题-composer-PHP中文网

composer卡在“resolving packages”并报403是因github未认证api请求超限（每小时60次），需配置全局github oauth token（composer config -g github-oauth.github.com ）并将auth.json权限设为600。

解决composer使用过程中因github api限流导致的依赖安装失败问题

为什么 composer install 会卡在 “Resolving packages” 并报 403 或 “rate limit exceeded”

这不是网络不通、镜像没换对，也不是 Composer 本身坏了——是 GitHub 对未认证 API 请求做了硬性限制：每小时最多 60 次。Composer 在解析依赖树时，只要包 source 是 GitHub（比如 dev-main、dev-feature/xxx、fork 后没改 source 的包），就会调用 https://api.github.com/ 查 tag、commit、zipball 地址等元数据。没 token 就算你只装一个包，也可能触发限流。

典型现象包括：
- Could not fetch https://api.github.com/...: 403 Forbidden
- API rate limit exceeded for xxx.xxx.xxx.xxx
- Failed to download vendor/package: GitHub API limit (60 calls/hr) is exhausted
- 甚至伪装成 404 Not Found（GitHub 为防探测故意返回）

必须用 `github-oauth.github.com` 配全局 token，而不是写进项目或改 composer.json

项目级配置（如 composer config github-oauth.github.com）只会写入项目根目录下的 auth.json，但 Composer 解析依赖链的阶段（即访问 Packagist 获取元数据、递归查 GitHub 仓库信息）发生在安装前，此时只读全局配置。项目级 auth.json 只在后续下载 zip 或 git clone 时才生效，无法解决“解析失败”这个根本卡点。

composer config -g github-oauth.github.com <your_token></your_token> 才是正确命令，它把 token 写进 ~/.composer/auth.json（Windows 是 %APPDATA%\Composer\auth.json）
token 必须勾选 repo（不是 public_repo）和 read:packages；fine-grained token 优先，classic token 仍可用但已逐步弃用
auth.json 文件权限必须是 600（Linux/macOS），否则 Composer 会静默忽略它：运行 chmod 600 ~/.composer/auth.json
验证是否生效：composer config -g github-oauth.github.com 应输出 token 前几位；composer diagnose 中应显示 GitHub API: OK

CI/CD 环境里不能靠本地配置，得用环境变量安全注入

GitHub Actions、GitLab CI 等环境每次都是干净容器，composer config -g 生成的 auth.json 不会持久化。硬编码 token 到脚本或提交到仓库是严重安全风险。

Ainative Git Workflow

Git 提交、PR 与分支规范，对 AI 归属零容忍。适用于创建提交、编写提交信息、创建 Pull Request。

下载

GitHub Actions 推荐直接用内置 secrets.GITHUB_TOKEN（自动具备当前 repo 权限）：
composer config -g github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
其他 CI 或私有 runner，用 COMPOSER_AUTH 环境变量最稳妥：
export COMPOSER_AUTH='{"github-oauth":{"github.com":"ghp_abc123..."}}'
避免在命令行历史或日志中泄露：PowerShell 下 token 含 $ 符号需单引号包裹；所有 CI 日志应设为 masked
不要用 repositories + options.http.header 这种写法——Composer 不识别该字段，且极易把 token 提交进 Git

配完 token 还报错？先检查这四件事

token 配了 ≠ 一定生效。很多“已配置却仍 403”的问题，其实卡在下游环节：

执行 composer install 的用户，跟运行 composer config -g 的不是同一个（比如用了 sudo 或切换了系统用户）
公司代理拦截了 Authorization 请求头——现象是 curl -H "Authorization: token xxx" https://api.github.com/rate_limit 返回 401，但浏览器能正常访问
PHP curl 扩展被禁用，或 SSL 证书不可信（尤其旧版 CentOS）；可运行 php -r "print_r(get_headers('https://api.github.com'));" 测试基础 HTTPS 是否通
token 已过期（fine-grained token 有明确有效期）或被手动删除；composer config -g github-oauth.github.com 输出为空，说明配置丢失