composer http basic认证失败主因是auth.json路径错误、权限非600、域名不匹配或字段名误写；必须放~/.composer/auth.json（linux/macos）或%appdata%\composer\auth.json（windows），且结构为{"http-basic":{"domain":{"username":"oauth2","password":"token"}}}。
HTTP Basic 认证是 Composer 连私有仓库最常用、也最容易配错的方式——它不报错，只静默跳过；不提示缺什么，只让你卡在 “Could not find package” 或 “401 Unauthorized”。
auth.json 放哪、字段怎么写才被读取
Composer 只在两个位置找 auth.json：用户级（全局）和项目级（根目录）。但行为完全不同：
- Linux/macOS 全局路径必须是
~/.composer/auth.json，不能是./auth.json或~/auth.json - Windows 全局路径是
%APPDATA%\Composer\auth.json，不是%USERPROFILE%\.composer\auth.json - 项目级
auth.json必须和composer.json同级，且仅在该目录下运行composer install时生效（CI 环境推荐用这个） - 权限必须是
600：chmod 600 ~/.composer/auth.json，否则 Composer 直接忽略文件 - 字段名必须是
http-basic，不是https-basic、basic-auth或auth
正确结构示例：
{ "http-basic": { "gitlab.example.com": { "username": "oauth2", "password": "glpat-xxx" } } }
repositories.url 和 auth.json 的域名必须完全一致
Composer 匹配认证凭据时，只比对 URL 中的 host 部分（不含协议、端口、路径），且区分大小写、严格字符匹配：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 如果
repositories.url是https://gitlab.example.com:8080/acme/utils.git，那auth.json里 key 必须是"gitlab.example.com:8080" - 如果 URL 是
https://gitlab.example.com/acme/utils.git，key 就只能是"gitlab.example.com"，多一个:或少一个.都失败 - 不能写成
"https://gitlab.example.com"或"gitlab.example.com/acme"—— 这些都不是合法 host - GitLab 的
username字段通常填oauth2（HTTPS + Token 场景），不是你的登录用户名
为什么 composer install 报 401 却没提示缺凭证
401 错误本质是 HTTP 层拒绝，说明 Composer 已发起请求，但服务端未收到有效认证头。常见真实原因：
- Token 权限不足：GitLab 要
read_api+read_repository；Private Packagist 要带readscope 的 API token - 密码字段留空字符串
""，不是null、不是删掉该键、也不是" "（带空格） -
secure-http配置冲突：若私有源用 HTTP（非 HTTPS），需在composer.json的config段设"secure-http": false，否则 Composer 直接拒发请求 - GitLab 实例启用了反向代理或自定义路径前缀（如
/gitlab），但url没对应调整，导致认证头被中间件剥离
require 的包名必须和私有库 composer.json 的 name 字段一字不差
Composer 不按 Git 路径查包，只认目标仓库根目录下 composer.json 里的 name 字段：
- 私有库中写了
"name": "acme/utils"，你就必须require"acme/utils": "dev-main" -
"Acme/utils"、"acme-utils"、"utils"全部失败 - dev 分支必须加
dev-前缀："dev-main"可行，"main"会被当成模糊约束去 Packagist 查 - 如果私有库没打任何 tag，
dev-main是唯一可 resolve 的版本（除非你改了默认分支名）
真正容易被忽略的是：所有这些配置项之间没有强关联校验，错一个就静默失效。调试时别猜，先用 composer config --list 看实际加载了哪些 auth，再用 composer diagnose 检查 secure-http 和网络连通性，最后手动 curl -v -u user:token https://gitlab.example.com/api/v4/projects/... 验证凭证是否真能过网关。
