composer私有包http认证依赖auth.json而非composer.json，应置于家目录，格式为json且仅含http-basic字段，域名须与仓库url主机名完全一致，密码推荐使用personal access token。
Composer 私有包的 HTTP 认证不是靠 composer.json 里写密码实现的，而是依赖本地配置的 auth.json 文件——直接往 composer.json 填账号密码等于把凭证明文提交到代码库，非常危险。
auth.json 文件该放哪、怎么写
Composer 查找 auth.json 的顺序是：当前项目根目录 → 当前用户家目录（~/.composer/auth.json 或 Windows 上 %APPDATA%\Composer\auth.json）。推荐放家目录，避免误提交。
内容格式必须是 JSON，且只包含 http-basic 字段，不能有注释：
{
"http-basic": {
"your-private-repo.com": {
"username": "your-username",
"password": "your-token-or-password"
}
}
}
- 域名必须和
composer.json中仓库的url主机名完全一致（比如用https://pkg.example.com就填pkg.example.com，不能漏掉pkg.） - 密码字段建议用 Personal Access Token（如 GitLab/GitHub 的 token），而不是真实密码；部分私有仓库（如 Satis、Artifactory）也支持 token 替代密码
- 如果私有源走 HTTPS 但证书自签，Composer 默认会拒绝连接——此时需在
auth.json同级加config.json并设"secure-http": false，但仅限内网环境，切勿在公网项目中关闭
为什么 vendor install 时还是报 401？常见卡点
HTTP 401 错误几乎都源于认证凭据没被正确送达，而不是密码错。重点排查这几处：
- 运行
composer config --global --list看是否真读到了auth.json；若输出里没有http-basic相关项，说明文件路径不对或格式非法（比如多了一个逗号、用了单引号） - 私有仓库 URL 在
composer.json的repositories里写的是git@地址？Composer 不会拿auth.json去配 SSH，必须改成https://协议才能触发 HTTP Basic 认证 - 某些私有源（如 Nexus Repository）要求用户名/密码 Base64 编码后传入，但 Composer 会自动处理，你只需填原文——别自己提前编码，否则反而失败
- 公司代理或防火墙拦截了
Authorization请求头？可临时用curl -v -u user:pass https://your-repo.com/packages.json验证基础连通性
用 gitlab.com 私有 Group Package 怎么配
GitLab 的私有 Group 或 Project 包，本质仍是 HTTP Basic 认证，但必须用 Personal Access Token 且权限要开对：
- Token 必须勾选
read_api和read_repository（如果包是通过 Git 源安装）；若走 GitLab Package Registry（https://gitlab.com/api/v4/groups/xxx/-/packages/composer），还需read_package_registry - auth.json 中的 host 填
gitlab.com，不是你的 group 名或子域名 -
composer.json 里仓库 type 要设为
composer，URL 指向 GitLab 的 Composer Registry endpoint，不是 Git 仓库地址 - GitLab 15.1+ 对未验证邮箱的账户限制 API 访问，确保 token 所属账号已验证邮箱，否则始终 401
最常被忽略的是：auth.json 文件权限。Linux/macOS 下若权限太宽（比如 755），Composer 会直接拒绝读取并静默跳过——必须是 600 或至少 640。Windows 用户则要注意不要让编辑器偷偷加 BOM 头，会导致 JSON 解析失败。
