Composer 安装扩展包时 GitHub API 速率限制绕过策略-composer-PHP中文网

直接配 github personal access token 是唯一稳定解法，其他手段（如换镜像、清缓存）只能缓解，不能绕过认证限流本身；composer 默认未认证调用 https://api.github.com/ 获取元数据，每小时仅 60 次额度，需通过 composer config --global github-oauth.github.com 配置带 repo 权限的 classic token，并确保 auth.json 权限为 600。

composer 安装扩展包时 github api 速率限制绕过策略

直接配 GitHub Personal Access Token 是唯一稳定解法，其他手段（如换镜像、清缓存）只能缓解，不能绕过认证限流本身。

为什么 `composer install` 会卡在 GitHub API 限速上

Composer 默认用未认证方式调 https://api.github.com/ 获取包元数据（比如 tag 列表、composer.json 内容、dev 分支最新 commit），每小时仅 60 次请求额度。哪怕你本地 git clone 正常，只要 Composer 走 API 就可能被拒——错误不是 404 或超时，而是明确的 403 Forbidden 或 429 Too Many Requests，日志里常出现 Loading composer repositories with package information 卡住或 Could not fetch https://api.github.com/...。

注意：dist 包下载走的是 Packagist CDN，不受此限；出问题的永远是 source 模式下的元数据查询。

怎么正确配置 `github-oauth.github.com`

Token 必须带 repo 权限（public_repo 对公开项目够用），且必须通过 composer config --global 写入全局凭据文件，不是塞进环境变量或 composer.json。

GitHub Hosts CN

GitHub Hosts 更新工具（仅限中国用户），安全更新系统hosts文件，保留原有非GitHub条目，仅替换GitHub相关地址。支持备份恢复和风险提示。用于解决GitHub访问问题。

下载

去 https://github.com/settings/tokens/new 生成 classic token，勾选 repo（别选 fine-grained，它默认有有效期且权限粒度太细）
执行命令：composer config --global github-oauth.github.com <your_token_here></your_token_here>（注意：不要加引号，PowerShell 用户建议用 cmd 或单引号包裹）
验证是否写入：composer config --global --list | grep github-oauth 应显示脱敏后的 token 哈希
立刻检查文件权限：chmod 600 ~/.composer/auth.json（Linux/macOS），权限不是 600，Composer 会静默忽略该文件

为什么配了 token 还报 403 或超限

不是 token 无效，而是 Composer 没真正用上它。常见失效点：

执行 composer config --global 的用户和运行 composer install 的不是同一个（比如 CI 中用 root 账户跑命令，但 token 配在普通用户下）
项目根目录存在 auth.json，它会覆盖全局配置；用 composer config --list 查看实际生效位置
用了镜像源（如阿里云、清华）后误以为“不用 token”，其实镜像只缓存 Packagist 元数据，GitHub API 请求仍走原域名，token 必须配 github.com
CI 环境没注入 token，或用了过期的 classic token（虽然默认永不过期，但可被手动删除）
PHP 禁用了 curl 或 SSL 验证失败（尤其某些旧版 CentOS），导致 Authorization 头根本没发出去

CI 环境和多用户共享网络的特别处理

GitHub Actions、GitLab CI 等场景不能复用个人 token，应使用平台提供的 secrets.GITHUB_TOKEN（它自动具备当前仓库权限，且生命周期绑定 workflow）。

GitHub Actions 中设环境变量：COMPOSER_AUTH='{"github-oauth":{"github.com":"${{ secrets.GITHUB_TOKEN }}"}}'
公司内网多人共用出口 IP 时，必须确保每人配独立 token——限流按认证身份计数，不按 IP
避免在 composer.json 里硬编码 token 或写 "options": {"http": {...}}，这不仅无效，还会把密钥提交到 Git
如果项目完全不依赖 GitHub VCS 包（即所有依赖都来自 Packagist），可额外加镜像源加速：composer config --global repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/，但 token 仍建议保留以防意外 fallback

真正容易被忽略的是 auth.json 文件权限和 CI 中 token 注入方式——这两处出错，token 就等于没配。