私有包安装失败，大概率是 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 不一致。
- 检查
composer.json的repositories：如果写的是https://gitlab.example.com/api/v4/groups/my-group/-/packages/composer，auth.json必须配"gitlab.example.com"，不能写成"https://gitlab.example.com"或"gitlab.example.com:443" - 运行
composer config --global --list看是否意外覆盖了github-oauth或其他认证项，干扰判断 - 临时加
-v参数重试：composer install -v，看日志里是否出现Reading authentication information from auth.json
安全与协作场景下的注意事项
auth.json 包含凭证，绝不能提交到 Git。项目级配置务必加进 .gitignore；全局配置则要注意多项目共享时的权限边界。
- CI/CD 中建议用环境变量注入：通过
COMPOSER_AUTH环境变量传入 base64 编码后的 JSON 字符串，避免文件落盘 - GitHub Actions 可用
composer config http-basic.xxx命令动态写入，执行完立即清理 - 团队内若用统一私有源，可封装一个
setup-composer-auth脚本，校验auth.json结构并提示缺失字段，比手动编辑更可靠
真正卡住人的往往不是语法，而是域名拼写、协议头遗漏、Token 权限不足（比如没勾选 read_package_registry），这些细节不打日志、不报明确错误，只能靠比对和验证来揪出来。
