Composer怎么设置Github OAuth 授权访问私有仓库【教程】

根本原因是未配置或权限不足的gitHub OAuth Token，因github已弃用密码认证且composer默认走https调用API；需用classic类型token并全局配置composer config -g github-oauth.github.com ，勾选repo等权限，存于auth.json，不可硬编码。

Composer 访问 GitHub 私有仓库失败，根本原因通常是未配置 OAuth token 或 token 权限不足，而不是“教程没看懂”——直接配对即可，但细节错一个就 401。

为什么必须用 OAuth token 而不是密码或 ssh？

GitHub 已全面弃用密码认证（2021 年起），SSH key 仅适用于 git clone 场景，而 Composer 的 composer install 和 composer update 默认走 HTTPS 协议，依赖的是 GitHub API 认证。没有有效 token，Composer 就会被拒绝访问私有 repo，报错类似：

Failed to download vendor/private-repo: The 'https://api.github.com/repos/vendor/private-repo' URL could not be accessed: HTTP/1.1 401 Unauthorized

• OAuth token 必须带 repo 权限（不是只勾 public_repo）
• 不能用 GitHub app token 或 fine-grained token（除非显式配置为 github-oauth 类型，但兼容性差）
• token 不要硬编码在 composer.json 中——它属于凭证，应存在本地配置里

怎么生成并全局配置 GitHub OAuth token？

执行这条命令，按提示粘贴你的 token：

composer config -g github-oauth.github.com 

这条命令会把 token 写入全局配置文件（通常是 ~/.composer/auth.json），对所有项目生效。关键点：

• token 必须是 classic 类型，在 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) 创建
• 勾选 repo（含私有库读写）、read:packages、delete:packages（如用 GitHub Packages）
• 别用 --global 拼写错误的参数，正确是 -g；若误输，可用 composer config -g --unset github-oauth.github.com 清除
• 配置后可运行 composer config -g github-oauth.github.com 验证是否存入（输出应为 ***）

私有包 require 时要注意什么？

即使全局配了 token，如果 composer.json 里没声明正确的 VCS 类型或源地址，Composer 仍会跳过认证流程。确保满足以下任一条件：

• 私有包已注册在 Packagist.org（且你有维护权限），则只需 "vendor/private-repo": "^1.0"，Composer 自动识别为 GitHub repo
• 未上 Packagist，则必须在根项目 composer.json 的 repositories 中显式声明：

{   "repositories": [     {       "type": "vcs",       "url": "https://github.com/vendor/private-repo"     }   ] }

注意：url 必须是 HTTPS 格式（不能是 git@…），且域名是 github.com（不是 github.enterprise.com）；如果是 GitHub Enterprise，需单独配置 github-oauth.github.enterprise.com。

调试和常见失效场景

token 配了却还是 401？先检查这几处：

• 运行 composer diagnose —— 它会明确告诉你 “GitHub API is accessible” 还是 “not accessible”，比盲猜快得多
• 确认 token 没过期（classic token 可设有效期，别选 “No expiration” 外的 90 天选项，容易遗忘）
• CI 环境（如 GitHub Actions）中，不要复用本地 auth.json，应通过 secrets.GITHUB_TOKEN 注入，并在 workflow 中用 composer config github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}
• 如果你用的是 GitHub SSO（企业绑定），token 必须在 SSO 授权页手动批准该 token 访问对应组织，否则即使 token 有效也会被拦截

最常被忽略的一点：GitHub 的 rate limit 是按 IP + token 共享的，多人共用一个 token 会导致频繁触发限制，表现就是偶发 403；每个开发者应使用自己的 token，而不是团队共享一个。