composer 本身不处理 api 认证或限流，相关错误源于 packagist 或私有仓库的认证拦截；需通过 auth.json 正确配置 bearer 或 http-basic 凭据，并确保域名精确匹配仓库 url。
Composer 本身不处理 API 认证或限流，它只是 PHP 的依赖管理工具；你遇到的“需要 Bearer Token 才能下载包”问题，实际来自 Packagist.org 或私有仓库（如 GitHub Packages、GitLab Registry、Satis）的认证拦截，而非 Composer 自身逻辑。
为什么 composer install 报错 401 Unauthorized 或 429 Too Many Requests
这类错误通常出现在以下场景：
- 你正在安装一个托管在 GitHub/GitLab 私有仓库的包，而该仓库启用了 token 访问控制
- 你频繁访问 Packagist.org（尤其使用
packagist.org镜像或自建 Satis），触发了 IP 级限流 - 你在 CI/CD 中未配置凭据，导致 Composer 尝试匿名拉取私有包失败
注意：Bearer Token 不是 Composer 的配置项，而是 HTTP 请求头的一部分 —— Composer 通过 auth.json 文件将 token 注入到对特定仓库的请求中。
如何正确配置 auth.json 支持 Bearer Token 认证
Composer 从 auth.json 读取凭证，并在向指定仓库发起 HTTP 请求时自动添加 Authorization: Bearer <token></token> 头。关键点在于仓库 URL 必须与 auth.json 中的域名完全匹配（含协议、端口）。
常见写法示例：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "your_personal_access_token"
}
},
"bearer": {
"packages.example.com": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
说明：
-
bearer字段是 Composer 1.10+ 和 Composer 2.0+ 原生支持的，专用于Authorization: Bearer场景 - 域名必须精确匹配仓库
repositories中定义的 URL 主机名（例如"https://packages.example.com"对应"packages.example.com"） - 不要把 token 写进
composer.json—— 它会被提交到代码库，且不被 Composer 解析为认证凭据 -
auth.json默认位置是COMPOSER_HOME/auth.json（通常是~/.composer/auth.json），也可用COMPOSER_AUTH环境变量注入 JSON 字符串（适合 CI）
GitHub Packages 和 GitLab Registry 的典型配置差异
GitHub Packages 要求 token 具备 read:packages 权限，并使用 github.com 作为 bearer 域名；GitLab Registry 则常要求 api.gitlab.com 或自建实例域名，且部分版本只认 http-basic + oauth2 用户名 + token 密码组合。
例如 GitHub Packages 正确配置：
{
"bearer": {
"github.com": "ghp_xxx..."
}
}
而 GitLab 若返回 403 Forbidden，可能需改用：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-xxx..."
}
}
}
原因：GitLab Registry 的认证接口有时不接受裸 Bearer 头，而是期望 Basic Auth 包装后的 token。
如何验证 token 是否生效并绕过限流
限流本身无法靠 Composer 配置绕过，但正确配置认证后，请求会绑定你的账户配额（而非 IP），从而避免共享限流阈值。验证方式如下：
- 运行
composer config --global --list | grep -i auth确认全局auth.json已加载 - 执行
composer diagnose—— 它会检查auth.json格式和仓库连通性 - 加
-vvv参数重试安装：composer require vendor/private-package -vvv，观察日志中是否出现Authorization: Bearer或Authorization: Basic - 若仍限流，检查 token 是否过期、权限是否足够（如 GitHub 需勾选
read:packages）、仓库 URL 是否带v1或api/v4等路径前缀（这些会影响域名匹配）
最易忽略的一点：Composer 不会为 HTTPS 重定向后的最终 URL 重新匹配 auth.json 中的域名 —— 如果仓库配置了 302 跳转，而跳转目标域名不在 auth.json 中，认证就会失效。
