根本原因是未配置或权限不足的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，而不是团队共享一个。
