私有包安装失败，大概率是 auth.json 没配对位置、没用对格式，或权限没开全。
auth.json 放哪儿才生效
Composer 查找 auth.json 有固定优先级：当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer/ 或 %APPDATA%\Composer\）→ 全局配置目录。项目级配置最可控，推荐优先放项目根目录；若多人共用同一私有源，再考虑全局配置。
- 项目级：
./auth.json（与composer.json同级） - 全局级（Linux/macOS）：
~/.composer/auth.json；Windows：%APPDATA%\Composer\auth.json - 路径错误时 Composer 不报错，只静默跳过认证 —— 这是常见排查盲点
auth.json 的正确结构和字段写法
必须是合法 JSON，顶层是对象，http-basic 是最常用类型。注意域名要精确匹配仓库 URL 的 host 部分（不含协议和路径），大小写敏感，不带尾部斜杠。
{
"http-basic": {
"gitlab.example.com": {
"username": "your-token-or-username",
"password": "your-personal-access-token"
},
"packagist.company.com": {
"username": "api",
"password": "abc123def456"
}
}
}
-
username和password字段名不能写成user或token，否则被忽略 - 私有 GitLab/GitHub 用 Personal Access Token 当
password，username填任意非空字符串（如token）即可，但不能留空 - 若仓库启用了 bearer token 认证（如某些 Nexus 或 Artifactory），需用
github-oauth或自定义config.platform配合插件，auth.json原生不支持 bearer
为什么 composer install 还是提示“Could not fetch”
错误信息里出现 401 Unauthorized 或 403 Forbidden，说明认证已触发但失败；若出现 404 Not Found 或直接超时，则大概率根本没走认证流程 —— 很可能域名不匹配，或 composer.json 中仓库配置的 url 协议/端口/路径与 auth.json 中的 host 不一致。
