最通用、最可控的 http basic 认证方式是使用 auth.json，但必须严格满足域名匹配、字段存在、密码非空（private packagist 等特例除外）三点，否则认证静默失效；ci 场景下应将 auth.json 置于项目根目录而非依赖全局配置，且需通过 composer diagnose 和 -vvv 日志验证域名与包名是否完全匹配。
直接结论：用 auth.json 配 http-basic 是最通用、最可控的方式，但必须严格满足域名匹配、字段存在、密码非空（除非 Private Packagist 等特例）这三点，否则认证静默失效。
为什么 composer config --global http-basic... 常常不生效
这个命令默认写入全局 auth.json（位于 ~/.composer/auth.json），但在 CI/CD 容器、Docker 构建或某些共享部署环境里，该路径可能不可写，或根本没加载用户级配置。更关键的是：composer install 优先读取项目根目录下的 auth.json，它会覆盖全局配置。
- CI 场景下，应始终把
auth.json放在项目根目录（和composer.json同级），而非依赖全局配置 -
composer config命令生成的配置，若未加--auth参数，可能写进config.json而非auth.json，导致认证被忽略 - 执行
composer config --list --auth可确认当前生效的认证项是否已载入
auth.json 的结构陷阱
看似简单，但字段名、嵌套层级、域名拼写错一个字符就会让认证完全跳过——Composer 不报错，只当公开包处理，最终表现为 401 Unauthorized 或 403 Forbidden。
-
http-basic外层是对象，不能是数组；键名必须是仓库**域名**（如"repo.example.com"），不能带https://或路径 - 用户名和密码字段必须存在，且值为字符串；Private Packagist 要求
password是空字符串""，不是null或缺失 - Bitbucket 在 Composer 2+ 中已废弃
http-basic.bitbucket.org，必须用bitbucket-oauth.bitbucket.org字段，否则认证不触发
HTTPS 私有 Git 仓库怎么填凭证
GitHub、GitLab、自建 Git 服务大多支持 HTTPS + Basic Auth，但凭证传递方式有差异：
- GitHub 私有库：必须用
github-oauth.github.com字段，填入 Personal Access Token（PAT），密码字段不参与 - GitLab 私有实例：用
http-basic，域名填实际 GitLab 地址（如"gitlab.example.com"），用户名可为任意非空字符串，密码填 PAT - 通用 HTTPS Git：URL 写成
https://oauth2:TOKEN@git.example.com/vendor/repo.git也可行，但 Token 暴露在 URL 和日志中，不推荐
认证失败时最该先查什么
别急着重配，先验证三件事：
- 运行
composer diagnose—— 它会检查auth.json是否可读、格式是否合法、是否有权限问题（如 600 权限缺失） - 执行
composer install -vvv，看日志里请求的 Host 是否和auth.json中的域名完全一致（注意大小写、子域、端口） - 确认私有仓库的
composer.json里name字段和你在require中写的包名**逐字符一致**，否则 Composer 根本不会尝试去那个仓库找
真正容易被忽略的点是：认证只在「Composer 确认要从某个仓库拉取包」时才触发；如果包名不匹配、repositories 类型写错（比如漏掉 "type": "vcs"）、或者仓库 URL 少了 .git 后缀，整个流程就绕过了认证环节——你看到的 404 或 403，其实跟账号密码毫无关系。
