根本原因是auth.json路径、权限、字段名及域名key必须严格匹配：Linux/macOS为~/.composer/auth.json且chmod 600；字段仅认"http-basic"；域名key须与repositories.url的host完全一致（含端口），否则Composer静默跳过。
私有仓库访问权限受限，根本不是“配得不够多”，而是 Composer 在几个关键节点上严格校验且静默跳过——错一个就完全不走认证流程，也不报错。
auth.json 路径、权限、字段名三者必须同时正确
Composer 只在固定路径读取全局认证文件，写错位置等于没配：
- Linux/macOS 必须是
~/.composer/auth.json，不是项目根目录、不是~/.config/composer/auth.json - Windows 必须是
%APPDATA%\Composer\auth.json - 权限必须是
600：运行chmod 600 ~/.composer/auth.json，否则 Composer 直接忽略该文件 - 字段名只能是
http-basic，写成github-oauth、gitlab-token或oauth2都无效（github-oauth是 config 命令专用，不用于 auth.json） - 域名 key 必须和
repositories.url的 host 完全一致：比如gitlab.example.com:8080和gitlab.example.com是两个不同 key
repositories 配置漏掉 "type": "vcs" 就静默失效
哪怕 URL 写对了、auth.json 也放对了，只要没显式声明 "type": "vcs"，Composer 就当它不存在——不报错、不提示、不尝试克隆。
- 不能写成
"type": "git"或"type": "package"，只认小写的vcs - URL 必须是可直接
git clone的地址：https://gitlab.example.com/group/pkg.git（缺.git后缀会失败） -
repositories字段必须位于composer.json顶层，嵌套在config或scripts下无效 - 若用 SSH 地址（如
git@gitlab.example.com:group/pkg.git），需确保ssh -T git@gitlab.example.com能通
packagist.org 默认开启，私有源永远排第二
即使你写了十行私有仓库配置，只要没关掉官方源，Composer 就先打 packagist.org；只有它返回 404 才 fallback 到你的源。重名包、vendor 段冲突、甚至只是名字拼写相近，都会导致私有包被跳过。
- 必须在项目级
composer.json根层级加："packagist.org": false - 该字段不能塞进
repositories数组里，也不能缩进 - 私有源建议置顶，避免被其他 repository 条目干扰顺序
- 若用 Artifactory/Satis，URL 末尾斜杠
/不可省略，少一个就是 404
HTTPS 证书或 DNS 层不通，Composer 会卡住或报 SSL error
Composer 依赖系统级 cURL 和 OpenSSL，不走浏览器代理，也不读 ~/.curlrc。很多“认证失败”其实是底层网络根本没通。
- 先手动测试：
curl -I https://your-repo.com/packages.json—— 如果失败，Composer 必然失败 - 若用自签名或内网 CA 证书，必须把根证书加到系统信任链：
sudo cp internal-ca.crt /usr/local/share/ca-certificates/+sudo update-ca-certificates - 别指望浏览器信任了就 OK；Composer 不读浏览器证书库
- 内网 DNS 解析失败也会表现为 SSL error 或超时，检查
nslookup your-repo.com
最容易被忽略的点是：所有认证逻辑都基于 host 的精确字符串匹配——协议、端口、子域、斜杠、大小写，差一点，凭证就白配。这不是 bug，是设计使然。
