自定义仓库不生效主因是repositories数组默认关闭packagist.org源，需显式添加{"type":"composer","url":"https://packagist.org","packagist":false}；vcs类型url必须可git clone且含.git后缀，name字段须严格匹配两段式包名。
自定义仓库不生效，90% 是因为 packagist.org 被静默关闭了，但你没手动加回来。
为什么 composer require 还是去 Packagist 找包？
只要你在 composer.json 里写了 repositories 数组，Composer 就会默认禁用隐式的 packagist.org 源——但它不会报错，也不会提醒你。结果就是：私有包装不上，连 monolog/monolog 都提示 “Could not find package”。
- 必须显式把官方源加回去：
{"type": "composer", "url": "https://packagist.org", "packagist": false}（注意不是删掉，而是加"packagist": false标记） - 私有源建议放
repositories数组最前面，兜底的 packagist 放最后 - 别信
composer config -g packagist false—— 全局关掉会影响所有项目，CI 构建容易翻车
vcs 类型 URL 写错，Composer 会静默失败
填 "type": "vcs" 时，url 不是网页地址，而是必须能直接 git clone 的 Git 地址。
- 必须带
.git后缀：https://gitlab.example.com/myorg/sdk.git✅，https://gitlab.example.com/myorg/sdk❌ - 不能是 GitHub Release 页面等 HTML 地址：
https://github.com/myorg/sdk/releases/tag/v1.2.0→ Composer 不解析 HTML - HTTPS + token 拼接写法（如
https://token:x-oauth-basic@github.com/...）已弃用，凭据必须走auth.json - 验证方式很简单：
git ls-remote -h https://gitlab.example.com/myorg/sdk.git能列出分支才算通
多个 repositories 怎么控制哪个包走哪个源？
Composer 不是“fallback 查找”，而是“顺序匹配 + 不回退”。它不会在第一个源没找到时自动去第二个源试，除非你明确告诉它“这个包名归这个源管”。
-
vcs类型只对name完全匹配的包生效，不支持通配符（比如myorg/*） - 想强制某包走私有源？用
"type": "package"手动声明元数据，绕过自动发现（适合不想暴露 Git 地址的场景） - 多个
composer类型源（如私有镜像+官方源）之间无优先级，靠数组顺序和包名前缀匹配决定流向 - 运行
composer config --list可确认当前实际生效的全部源（含全局 + 项目），避免本地配置干扰 CI
invalid repository 错误到底在报什么？
这个错误几乎从不表示网络不通，而是配置本身不合法 —— Composer 在发请求前就校验失败了。
-
"type": "composer"的url必须返回合法packages.json，且顶层必须有"packages"键；用curl -I https://your-repo.com/packages.json看状态码和响应体 -
"type": "vcs"的url必须是可git ls-remote的地址；Docker 里写localhost是指容器自己，得用host.docker.internal -
composer diagnose会直接指出哪条repository“failed to parse”，比看报错快得多 - 老版 Satis 或自建服务若返回结构不兼容（比如用
repo.packagist键），Composer ≥ 2.2 会直接拒收
最常被忽略的一点：vcs 仓库里的 composer.json 中 "name" 字段必须严格匹配 require 时写的包名，且必须是两段式（vendor/name），少一段或大小写错都会失败。
