结论：90%私有仓库下载失败是因repositories配置不合法或认证未加载，composer静默跳过请求直接报错；需逐级验证配置规则、url可达性、auth.json加载及默认源禁用。
直接告诉你结论：90% 的私有仓库下载失败，根本不是网络不通，而是 composer.json 里 repositories 配置不合法，或认证信息压根没加载——Composer 连请求都没发出去，就直接报错“Could not find package”或“Invalid repository”。
检查 repositories 配置是否满足 Composer 硬性规则
Composer 对不同 type 的仓库有严格校验，不满足就跳过、不报错、不发请求，只在最终阶段甩出模糊错误。
-
type: "vcs"必须配 Git/SVN/Hg 地址，且必须带.git后缀（如"https://gitlab.example.com/group/pkg.git"），写成网页地址会静默失效 -
type: "composer"要求 URL 可访问、返回合法 JSON，且路径末尾必须有/（如"https://artifactory.example.com/artifactory/api/composer/my-repo/"），少斜杠会拼成/packages.json导致 404 -
type: "package"不需要url字段，但必须提供完整package对象，含name、version、dist或source - 运行
composer diagnose，它会明确指出哪条repository“failed to parse”，比盲改快得多
验证私有仓库 URL 是否真实可达
别信 Composer 报错里的“Repository not found”，它可能连 DNS 都没查。用底层命令直连，看真实响应。
- 对
type: "composer"：执行curl -I https://your-repo.com/packages.json，确认返回HTTP/2 200且响应体是合法 JSON（顶层含"packages"键） - 对
type: "vcs"：执行git ls-remote -h https://your-git.com/user/repo.git，能列出 ref 才算通；若报fatal: unable to access，就是证书、代理或 DNS 问题 - Docker 场景下，
localhost指容器自身——想连宿主机服务，URL 得写成http://host.docker.internal:8080（Linux 需加--add-host=host.docker.internal:host-gateway启动）
确认 auth.json 是否被正确加载和解析
报 401 Unauthorized 或 Could not authenticate，大概率是凭证根本没读到，不是 Token 写错了。
- 运行
composer config --global --list | grep http-basic，如果输出为空，说明凭据压根没加载 -
auth.json必须放在~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），权限必须是600（Linux/macOS） - 域名必须完全一致：仓库 URL 是
https://gitlab.internal:8080/myorg/pkg.git，那么auth.json里http-basic的 key 就得是"gitlab.internal:8080"，端口不能省 - CI 环境中，必须通过
COMPOSER_AUTH环境变量注入 JSON 字符串，不可硬编码或挂载错误路径的文件
排查 packagist.org 默认源干扰
私有包始终 Could not find package？大概率是 Composer 还在优先查 packagist.org，根本没去你的私有源。
- 必须在项目级
composer.json中显式禁用默认源："packagist.org": false（这一行不能省，也不能写在全局配置里） - 确保
repositories数组里第一条是你的私有源，且type和url已通过前两步验证 - Artifactory/Satis 用户注意：Virtual 仓库必须启用
composer协议，Generic 类型仓库不兼容；Satis 构建后要确认packages.json能被curl直接访问到，否则 Composer 静默 fallback
最容易被忽略的是：Composer 不会告诉你哪一步卡住了，它只在最后汇总失败。所以不要从报错信息倒推，而要从 repositories 结构、URL 可达性、凭证加载、默认源开关这四层逐级验证——漏掉任意一层，都会让调试变成猜谜。
