HTTPS地址必须带.git后缀且能直接git clone，缺后缀如https://gitlab.example.com/acme/utils会导致“No valid composer.json”错误；URL须为可clone的Git地址，不能是网页或API地址；auth.json须严格按路径、权限、字段名（http-basic）、域名一致等要求配置；repositories必须顶层、type必须为"vcs"；require包名须与私有库composer.json中name字段完全一致。
HTTPS地址必须带.git后缀且能直接git clone
Composer 不会帮你补全或修正 URL。写成 https://gitlab.example.com/acme/utils（缺 .git）会导致拉取时提示 No valid composer.json was found，因为 Git 无法识别为有效仓库。它不是“找不到包”，而是根本没成功克隆下来。
- 正确写法只能是
https://gitlab.example.com/acme/utils.git或https://github.com/username/repo.git - 不能写网页地址（如
https://gitlab.example.com/acme/utils）、不能写 API 地址（如https://gitlab.example.com/api/v4/projects/...） - URL 中的域名必须和后续
auth.json里的 key 完全一致（不含端口、协议、路径）
auth.json 必须放对位置、字段名一个字都不能错
90% 的 HTTP Basic: Access denied 不是 token 无效，而是 auth.json 没生效——Composer 静默跳过，不报错也不提示。
- Linux/macOS：必须是
~/.composer/auth.json，不是项目根目录下的auth.json - Windows：必须是
%APPDATA%\Composer\auth.json - 权限必须是
600：chmod 600 ~/.composer/auth.json，否则直接忽略 - 字段名必须是
http-basic（不是https-basic、basic-auth或gitlab-http），结构严格如下：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-xxx"
}
}
}
其中 gitlab.example.com 必须和 repositories.url 中的 host 完全一致。
type 字段只能是 "vcs"，不是 "gitlab" 或 "git"
很多文档误写 "type": "gitlab" 或 "type": "git"，这会导致 Composer 完全忽略该仓库配置，不报错、不警告、不尝试拉取。
-
repositories必须是composer.json顶层字段，不能嵌套在config、extra或其他任意位置 - 每项私有源都必须显式写
"type": "vcs" - 多个私有库就写多个对象，顺序无关，但建议把最常用的那个放前面
require 的包名必须和私有库自身 composer.json 的 name 字段一字不差
Composer 不按 Git 路径匹配，只比对私有库根目录下 composer.json 里的 name 字段。差一个字符、大小写不对、vendor 段缺失，都会报 Could not find package。
- 如果私有库的
composer.json是{"name": "acme/utils"}，主项目require就只能写"acme/utils": "dev-main" - 不能写成
"Acme/utils"、"acme-utils"、"utils"，也不能省略acme/ - 分支版本必须加
dev-前缀："dev-main"可行，"main"或"*"会被当成模糊版本，失败
最容易被忽略的是：HTTPS 配置成功 ≠ 类能自动加载。下载进 vendor 后，还得确认私有库自己的 autoload 段是否定义正确，否则 new Class() 仍会报错。
