repositories必须是composer.json顶层数组，嵌套在config等字段中将被完全忽略；type须显式写"vcs"或"composer"，url需为可git clone地址且含.git后缀或末尾/；私有源须配auth.json、禁用packagist.org并确保包名严格一致。
repositories 必须是顶层数组，不能嵌套
Composer 只在 composer.json 最外层读取 repositories 字段。把它塞进 config、scripts 或 extra 里，就等于没写——Composer 完全无视，也不报错。
常见错误写法：
{
"config": {
"repositories": [{ "type": "vcs", "url": "https://gitlab.example.com/acme/utils.git" }]
}
}
正确位置必须和 require、autoload 并列：
{
"repositories": [
{ "type": "vcs", "url": "https://gitlab.example.com/acme/utils.git" }
],
"require": { "acme/utils": "dev-main" }
}
-
type必须显式写"vcs"，不是"git"、"package"，也不能留空 -
url必须是能直接git clone的地址：HTTPS 格式要带.git后缀，SSH 格式要符合git@gitlab.example.com:acme/utils.git规范 - 如果用 Artifactory 或 Satis 这类 Composer 协议仓库，
type应为"composer"，且url末尾必须有/
GitLab/Bitbucket 私有仓库必须配 auth.json，不是写在 composer.json 里
认证信息绝不能硬编码进 composer.json，否则会泄露 token；Composer 也根本不认这种写法。它只从固定路径的 auth.json 文件读取 HTTP Basic 或 OAuth 凭据。
Linux/macOS 路径是：~/.composer/auth.json（不是项目根目录）
Windows 路径是：%APPDATA%\Composer\auth.json
- 权限必须设为
600：chmod 600 ~/.composer/auth.json，否则 Composer 静默跳过 - GitLab 域名 key 必须和
repositories.url中的 host 完全一致（不含协议、端口、路径），例如gitlab.example.com:8080和gitlab.example.com是两个不同 key - Bitbucket 必须用 App Password，填在
bitbucket.org下，字段名是consumer-key，不是username/password
require 的包名必须和私有库 composer.json 里的 name 严格一致
Composer 不按 Git 地址匹配包，只比对私有库自身 composer.json 中的 name 字段。差一个字符、大小写不对、漏 vendor 段，都会报 Could not find package。
假设私有库根目录下 composer.json 写的是：
{ "name": "acme/utils", "version": "1.0.0" }
那么主项目 require 就只能写：
"acme/utils": "dev-main"
- 不能写成
"Acme/utils"（大小写敏感） - 不能写成
"acme-utils"（连字符 ≠ 斜杠） - 不能省略 vendor 段，比如只写
"utils" - 如果私有库没声明
name，Composer 会直接拒绝识别该仓库
不关掉 packagist.org，私有包永远排第二
默认情况下，Composer 会先查 packagist.org，再 fallback 到你配置的私有源。哪怕 URL 和 name 都对，只要公共源上没有同名包，它也不会主动去你的 GitLab 或 Satis 查——结果就是 Could not find package。
必须在项目级 composer.json 中显式禁用默认源：
{
"repositories": [
{ "type": "vcs", "url": "https://gitlab.example.com/acme/utils.git" }
],
"packagist.org": false,
"require": { "acme/utils": "dev-main" }
}
-
"packagist.org": false这一行不能少，也不能写成"packagist": false - 这是全局开关，影响整个项目所有依赖解析行为
- 如果用了 Satis 或 Artifactory，同样要加这一行，否则客户端仍会绕过你的镜像直连外网
auth.json 权限不对、packagist.org 没关、或者私有库自己漏了 name 字段——这三处出问题，Composer 都倾向于静默失败，而不是报明确错误。 
