必须将repositories写在composer.json顶层且type为"vcs"，嵌套或类型错误（如"git"）均被静默忽略；url须为可git clone地址（如含.git后缀）；auth.json需置于系统固定路径、权限600、域名严格匹配；require包名须与私有库composer.json中name字段逐字符一致。
repositories必须写在composer.json顶层，且type必须是"vcs"
Composer只认根级repositories数组，嵌套在config、extra或任意自定义字段里都无效。写错位置等于没配，执行composer require时根本不会查你的私有仓库。
类型必须明确写"type": "vcs"，不是"git"、"package"，也不能留空。大小写敏感，写成"VCS"或"vcs "（带空格）也会被静默忽略。
常见错误示例：
-
"type": "git"→ 无效，不报错但不生效 -
"url": "https://gitlab.example.com/acme/utils"→ 缺.git后缀，触发No valid composer.json was found -
"url": "https://gitlab.example.com/acme/utils/tree/main"→ 是网页地址，不是可clone的Git URL
正确写法：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/acme/utils.git"
}
]
}
URL必须是能直接git clone的地址，且以.git结尾
Composer内部会调用git clone拉取代码，所以url值必须满足终端可执行git clone <url></url>成功。它不解析HTML页面，也不走GitLab API。
验证方式很简单：在终端粘贴执行一遍，确认能clone下来再写进composer.json。
- HTTPS格式：必须带
.git，如https://gitlab.example.com/acme/utils.git - SSH格式：支持
git@gitlab.example.com:acme/utils.git，注意冒号分隔 - 禁用：
file://、~/、$HOME等路径写法，path仓库另配
GitLab和GitHub统一用vcs类型，不用区分gitlab或github——Composer没这种类型。
auth.json路径、权限、域名key三者必须同时正确
认证文件auth.json必须放在系统级固定路径，项目根目录下放一份完全无效。
- Linux/macOS：
~/.composer/auth.json，然后运行chmod 600 ~/.composer/auth.json - Windows：
%APPDATA%\Composer\auth.json
内容结构必须是http-basic包裹，且域名key必须与repositories.url的host完全一致：
- 如果
url是https://gitlab.example.com/acme/utils.git，key就得是"gitlab.example.com" -
gitlab.example.com:8080和gitlab.example.com被视为两个不同key，不能混用 - GitLab用Personal Access Token，
username固定为"oauth2"，password填"glpat-xxx"
权限不是600，Composer就直接跳过该文件，且不提示、不报错——这是90%认证失败的真实原因。
require包名必须与私有库composer.json的name字段逐字符一致
Composer查包不看Git路径，只比对私有仓库根目录下composer.json里的name字段。差一个字母、大小写、斜杠位置，都会报Could not find package。
- 私有库
composer.json写的是{"name": "acme/utils"} - 主项目
require就必须写"acme/utils": "dev-main" - ❌ 错误写法：
"Acme/utils"、"acme-utils"、"utils"、"acme/utils-dev"
分支名前必须加dev-前缀："dev-main"可行，"main"会被当成模糊约束去Packagist查，必然失败。tag同理，"v1.2.3"要求仓库存在名为v1.2.3的tag，且该tag指向的composer.json中version字段必须精确等于"1.2.3"。
auth.json权限设为600这件事，既不报错也不警告，但只要漏掉，整个流程就静默失效。
