composer中如何配置github-oauth授权_composer解决github接口频率限制【详解】

必须配置 github-oauth，因为未认证的 github API 请求限流仅60次/小时，而 composer 解析依赖、下载包等操作频繁调用该 API；配置后使用 Personal access Token 可提升至5000次/小时并支持私有库访问。

Composer 安装或更新依赖时频繁遇到 404 Not Found、429 Too Many Requests 或提示 GitHub API rate limit exceeded，根本原因是未配置 github-oauth，导致 Composer 默认以未认证方式调用 GitHub API，每小时仅限 60 次请求。

为什么必须配 github-oauth？

GitHub 对未认证的 API 请求严格限流（60 次/小时），而 Composer 在解析 composer.json、下载 ZIP 包、克隆私有仓库、甚至访问 public repo 的元数据时，都会触发 GitHub API。一旦项目依赖较多或 CI 频繁构建，极易触达上限。配置 github-oauth 后，请求将携带 Personal Access Token（PAT），额度升至 5000 次/小时，且支持私有库访问。

如何生成并写入 github-oauth token？

Token 必须具备 repo 作用域（私有库必需）和 read:packages（若用 GitHub Packages）。生成后，**不要硬编码在项目 composer.json 中**，应写入全局或用户级配置：

• 运行 composer config -g github-oauth.github.com （推荐，影响所有项目）
• 或手动编辑 ~/.composer/auth.json（linux/macOS）或 %appDATA%Composerauth.json（windows），确保格式为：

{     "github-oauth": {         "github.com": "ghp_xxx..."     } }

注意：auth.json 文件权限需设为 600（Linux/macOS），否则 Composer 会拒绝读取。

常见错误：token 无效或权限不足

即使 token 写对了，仍报错，大概率是以下原因：

• Token 已过期或被手动撤销（GitHub 不发通知）→ 重新生成并更新 auth.json
• Token 缺少 repo scope → 进入 GitHub Settings → Tokens，编辑 token 并勾选 repo
• 使用了 fine-grained token 但未授权对应 organization 或 repository → 改用 classic token，或仔细检查 fine-grained token 的 Resource access 配置
• CI 环境中误将 token 暴露在日志里 → 在 GitHub Actions 中用 ${{ secrets.GITHUB_TOKEN }}，并确保 composer config 命令不 echo 出 token

其他可选优化项

单纯配 github-oauth 能解限流，但若想进一步提速或绕过某些限制，可配合以下配置：

• 启用 GitHub ZIP 下载而非 Git 克隆：composer config -g prefer-stable true + 确保包有 dist.zip 类型发布（Composer 默认优先用 dist）
• 禁用 Git 钩子避免意外触发 API：composer config -g disable-tls false（仅调试用，生产不建议关 TLS）
• 若公司用 GitHub Enterprise，需额外配置 host：composer config -g github-oauth.ghe.example.com ，且确保 composer.json 中仓库 URL 使用该 host

真正容易被忽略的是：token 权限变更后，Composer 不会自动刷新缓存；遇到异常时，先删掉 ~/.composer/cache/ 下的 github-api 目录再重试。