Composer 需 GitHub Token 是为绕过未认证请求每小时60次的 API 限流，避免 composer install/update 因频繁查 tag/metadata 报 403；应配置全局或项目级 Token 并确保含 repo 权限。
Composer 用 GitHub Token 是为了绕过未登录时的 API 限流，否则 composer install 或 composer update 可能直接报错 403。
为什么 Composer 会突然要 GitHub Token？
GitHub 对未认证请求限制极严：每小时最多 60 次 API 调用。Composer 在解析 composer.json 依赖时，会频繁调用 GitHub API（比如查 tag、fetch metadata），尤其当项目用了大量私有包或 fork 的包时，很容易触发限流。错误典型表现为：
Failed to download vendor/package: Could not fetch https://api.github.com/repos/vendor/package/contents/composer.json?ref=..., will retry in 2 sec. Retrying... (2/3)
Could not authenticate against github.com
这不是你账号的问题，是 IP 共享限流 —— 即使没登 GitHub，也走的是匿名配额。
怎么配置全局 GitHub Token（推荐）
Token 存在本地配置里，Composer 自动带上 Authorization Header，不暴露在命令行或日志中。
- 去 https://www.php.cn/link/9c450eb90c31bc12f1691f235da5a0cc 创建 Personal Access Token，勾选
repo（读私有库必需）、read:packages（如果用 GitHub Packages）即可，不用给 admin 权限 - 执行命令写入全局配置：
composer config -g github-oauth.github.com <your_token_here></your_token_here> - 验证是否生效：
composer config -g github-oauth.github.com应输出 token 前几位（Composer 会自动掩码显示）
注意：-g 是全局配置，写入 ~/.composer/auth.json；别误用 -v（这是 debug 开关）或漏掉 github.com 这个 host 名。
私有项目单独配 Token（避免泄露到团队）
如果项目要提交 composer.json 到公开仓库，但又依赖私有 GitHub repo，不能把 Token 写进 auth.json 提交出去 —— 此时要用项目级配置 + 环境变量兜底。
- 在项目根目录运行：
composer config github-oauth.github.com "${GITHUB_TOKEN}"（注意双引号，让 shell 展开变量） - 确保 CI 或本地环境已设好
GITHUB_TOKEN环境变量（GitHub Actions 默认提供${{ secrets.GITHUB_TOKEN }}） - 该命令会在项目
composer.json里写入"config": { "github-oauth": { "github.com": "${GITHUB_TOKEN}" } }—— 但实际运行时 Composer 会优先取环境变量值，而非字符串字面量
这个机制容易被忽略：Composer 不支持直接在 composer.json 里写 ${VAR} 占位符，必须靠环境变量注入，否则会当普通字符串处理，认证失败。
Token 权限不够或过期了怎么办？
常见现象是：能装公开包，但拉私有 repo 报 404 或 403；或者某天突然失效。
- 检查 Token 是否被手动删掉：访问 https://www.php.cn/link/f4380fd29ac34f2610014e8361d088fb 确认状态
- 确认 Token 有
repo权限 —— 少了它，连私有库的 metadata 都拿不到，不是权限不足，是根本看不到仓库存在 - CI 场景下，GitHub Actions 的
GITHUB_TOKEN默认只对当前仓库有效，跨组织/跨账户私有库仍需自建 Token 并设为 secret - 不要复用 npm 的
token或其他平台 token —— GitHub Token 必须是 GitHub 发的，格式为ghp_...或旧版ghp_...
最麻烦的是：错误信息从不明确说“Token 权限不足”，永远只报 403 或 “could not fetch”，得靠排除法定位。
