Github API调用次数超限？为Composer配置Token告别Rate Limit报错

直接配置 GitHub Personal Access Token 即可解决“API rate limit exceeded”问题，否则 Composer 默认未认证请求受限于每小时60次；需勾选 repo 和 read:packages 权限，用 composer config --global github-oauth.github.com 配置，并确保 auth.json 权限为600、避免手动编辑。

这事儿其实很简单，核心就一句话：给你的 Composer 配上 GitHub Personal Access Token。如果不配，那你将永远被卡在每小时60次的匿名请求限额里，动弹不得。

为什么 composer install/update 会报 “API rate limit exceeded”

问题根源在于 Composer 的工作机制。当它解析项目依赖时——无论是读取 composer.json，还是查询 dev-master 这样的开发分支，抑或是拉取私有仓库的标签列表——默认都会向 GitHub API 发起未认证的请求。而 GitHub 对这类“匿名访客”的待遇相当苛刻：硬性规定每小时最多只能请求60次。关键是，这个限制是基于请求头来识别的，跟你换台机器、清空缓存甚至重装 Composer 都没关系，额度就是不够用。

哪些场景最容易触发这个报错呢？通常包括：

• 持续集成（CI）环境里反复重试 composer install 命令
• 项目依赖中包含了大量 fork 后却未修改 "source" 字段的包
• 在本地开发时频繁执行 composer update 或 create-project
• 身处公司或学校网络，多人共享同一个公网出口 IP，额度瞬间被耗尽

生成 Token 必须勾选哪些权限

创建 Token 时，权限配置的原则是“宁缺毋滥”，但关键项一个都不能少。访问 GitHub 的 Token 创建页面，选择生成 classic token 时，下面这两个权限是必须勾选的：

• repo：这是核心，用于读取公有和私有仓库的元数据。
• read:packages：同样必需，部分组织将私有包托管在 GitHub Packages，依赖此项才能读取。

至于 write:packages、delete:packages 或 admin:org 这类高危权限，则完全不需要。另外需要注意，尽管 fine-grained token 更精细安全，但目前的 Composer 版本还不支持，所以暂时还得使用 classic token。

配置命令和权限陷阱

配置命令本身不复杂：composer config --global github-oauth.github.com 。注意，这里是空格分隔，不是等号。这条命令会将 Token 写入 ~/.composer/auth.json 文件。然而，接下来的几个细节才是真正的“坑点”，稍不注意就会前功尽弃：

• 文件权限是关键：在 Linux 或 macOS 上，auth.json 的文件权限必须设置为 600（命令：chmod 600 ~/.composer/auth.json）。如果权限不对，Composer 会静默忽略这个文件，默默地退回到未认证模式，而你却浑然不知。
• Windows 下的粘贴问题：在 Windows PowerShell 中，如果 Token 里包含 $ 这类特殊字符，粘贴时可能会被截断。稳妥的做法是使用 cmd 命令行，或者用单引号将整个 Token 包裹起来：composer config --global github-oauth.github.com '$TOKEN'。
• 别手动编辑 JSON：强烈建议不要直接用文本编辑器去修改 auth.json。JSON 格式非常严格，错一个引号、少一个逗号，都会导致整个文件失效，Token 也就白配置了。

验证是否真正生效

配置完成后，怎么知道它真的起作用了？别只看 composer install 这次没报错就掉以轻心。下面这几招才是可靠的验证方法：

• 运行 composer config --global github-oauth.github.com 命令，如果配置成功，它会输出 Token 的前几位（后面部分会被自动掩码保护）。
• 带上 -v（详细）参数重新运行安装命令：composer install -v。仔细观察输出日志，如果出现了 Using GitHub token from configuration 这行提示，那才说明 Token 被成功加载并使用了。
• 终极验证法：直接用 curl 命令模拟 API 请求：curl -H "Authorization: token " https://api.github.com/rate_limit。查看返回结果中的 rate.limit 字段，如果显示是 5000（认证用户的高额度），而不是 60，那就大功告成了。

最后，对于 CI/CD 环境（例如 GitHub Actions），配置方式略有不同。应该使用 ${{ secrets.GITHUB_TOKEN }} 这样的方式注入，并且不要使用 --global 全局标志，以免污染构建服务器的配置。正确的姿势是使用项目级配置：composer config github-oauth.github.com "$GITHUB_TOKEN"。记住这一点，就能让自动化流程也畅通无阻。