composer如何配置私有GitHub仓库的访问令牌_composer令牌设置方法【详解】

必须用auth.json配置gitHub个人访问令牌（PAT）才能拉取私有仓库，字段名github-oauth大小写敏感且域名须为github.com，令牌需含repo权限，推荐用composer config命令安全写入，仓库type必须为vcs且url用https格式。

私有 GitHub 仓库必须用 auth.json 配置个人访问令牌（PAT）

Composer 默认无法拉取私有 GitHub 仓库，因为 GitHub 已停用密码认证，必须使用个人访问令牌（Personal access Token）。关键不是改 composer.json，而是配置全局或项目级的 auth.json 文件，让 Composer 在请求时自动携带 Authorization 头。

• 令牌需勾选 repo 权限（如果是组织仓库，还需 read:org）
• 不要把令牌硬编码进 composer.json 或 Git 提交——auth.json 默认被 Composer 忽略，且应放在 COMPOSER_HOME 目录下（通常是 ~/.composer/auth.json）
• 若项目需要独立凭证（如 CI 环境），可将 auth.json 放在项目根目录，但必须确保它不被提交；可通过 .gitignore 显式排除

auth.json 的正确结构和字段名不能写错

字段名大小写敏感、嵌套层级固定，写错会导致认证完全失效，且 Composer 不报明确错误，只会提示 Could not fetch 或 404 Not Found（实际是 401 被 GitHub 拦截后伪装成 404）。

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

• github-oauth 是固定键名，不是 github_oauth 或 githubAuth
• 域名必须是 github.com（即使你用 GitHub Enterprise，也得填对应实例域名，如 git.example.com）
• 令牌值不能带空格、换行或引号外的特殊字符；生成后建议立刻复制纯文本

使用 composer config 命令更安全地写入令牌

手动编辑 auth.json 容易出格式错误。推荐用 Composer 自带命令，它会自动处理 JSON 转义、路径定位和权限设置（如设为 600）。

• 全局配置（影响所有项目）：

  composer config -g github-oauth.github.com ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• 仅当前项目配置：

  composer config github-oauth.github.com ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• 执行后可验证是否生效：

  composer config -g --list | grep github-oauth

GitHub 私有包的 composer.json 中 repositories 必须用 vcs 类型

即使令牌配对了，如果 composer.json 里仓库类型写成 package 或漏掉 type，Composer 仍不会触发 OAuth 认证流程。

{     "repositories": [         {             "type": "vcs",             "url": "https://github.com/your-org/private-package"         }     ],     "require": {         "your-org/private-package": "^1.0"     } }

• type 必须是 vcs（不是 git 或 github）
• url 必须是 HTTPS 格式（不能是 git@ ssh 地址；SSH 方式走的是系统 ssh-agent，与 auth.json 无关）
• 如果包未发布到 Packagist，且你用了 dist 方式下载（如 "preferred-install": "dist"），需确认该私有仓库已启用 GitHub Releases，否则安装会失败

GitHub 的 OAuth 认证链很短：Composer 读 auth.json → 拼 Authorization: Bearer xxx → 请求 GitHub API → 获取 ZIP 或 clone 地址。任一环断开，表现都是“找不到包”，但真正卡住的地方往往在 auth.json 路径、字段名或令牌权限上。