Composer私有包拉取失败90%是repositories配置非法：type拼错、URL缺.git或/、未显式关闭packagist.org、auth.json路径/权限/域名不匹配等均导致静默跳过，根本未发起请求。
Composer拉取私有包失败，90%不是权限或网络问题，而是 repositories 配置本身非法——它压根没发请求，更谈不上“鉴权失败”。
为什么 composer diagnose 一跑就报 “failed to parse”
Composer 解析 repositories 数组时是严格校验的：任意一条配置字段缺失、拼写错误、URL 格式违规，整个数组就会被静默跳过。你看到的 Could not find package 或 Repository not found，其实是 Composer 根本没尝试访问你的私有地址。
-
type必须是"vcs"（不是"git"、"github"或拼错成"compsoer"） - VCS 类型的
url必须以.git结尾（如https://gitlab.example.com/myorg/pkg.git），带#branch或路径后缀会直接失效 -
type: "composer"的 URL 必须可 HTTP 访问、返回200、响应体是合法 JSON 且含顶层packages键，末尾必须有/（如https://satis.example.com/） - 多个
repositories条目中只要有一条type拼错，整块配置作废，不会继续解析后面的项
加了私有源却 still Could not find package
这不是 URL 写错了，是 Composer 默认仍优先查 packagist.org ——哪怕你只加了一条 vcs，它也不会自动去你配的地址找，除非你显式关掉官方源。
- 必须在
repositories数组末尾单独加一项：{"packagist.org": false}（注意键名是packagist.org，不是packagist或packagist.com） - 这项不能嵌套在其他仓库对象里，也不能放在开头；必须是独立对象，且位于私有源之后
- 别用
composer config -g repos.packagist false，这会污染全局，其他项目可能崩 - 如果项目级
composer.json里有repositories字段（哪怕空数组），它会完全屏蔽全局镜像配置
Could not authenticate 或 401 Unauthorized 怎么办
这不是密码错了，是凭证根本没加载。Composer 不会自动读取 ~/.gitconfig 或系统 SSH agent，必须显式提供认证信息。
- HTTPS 私有仓库：在项目根目录放
auth.json，内容为{"http-basic": {"gitlab.example.com": {"username": "xxx", "password": "token"}}}；确保文件权限是600，且域名与 URL 完全一致（gitlab.example.com≠https://gitlab.example.com） - SSH 私有仓库：URL 必须用
git@gitlab.example.com:myorg/pkg.git格式，且本地ssh -T git@gitlab.example.com能通 - 别信
composer config -g http-basic的输出——它可能“看起来成功”，但实际没生效；用composer install -vvv 2>&1 | grep -i "downloading"看真实请求头是否带Authorization - 企业内网常见中间人代理导致证书校验失败，临时调试可用：
composer config -g secure-http false和composer config -g cafile /dev/null
minimum-stability 导致 dev-main 报错却不提示版本问题
即使私有源和认证都对了，require 里写 "dev-main" 却报 Could not find package，大概率是稳定性策略拦住了。
- 默认
"minimum-stability": "stable"会直接过滤所有dev-、alpha、beta版本，连元数据都不去拉，所以不报“版本不匹配”，只报“找不到” - 临时验证：加
--stability=dev参数试装，如composer require myorg/pkg --stability=dev - 长期方案：在
composer.json中设"minimum-stability": "dev"并配"prefer-stable": true，既允许开发版又优先选稳定依赖 - 注意：改
minimum-stability是全局降级，可能意外升级其他包，上线前务必composer update --dry-run预览
真正卡住的地方往往不是 token 过期或 Git 地址不通，而是 repositories 里某一行少了个点、多了一个斜杠、或者 packagist.org 没关干净——这些错误不会报红字，只会让 Composer 安静地走开。
