必须将私有git仓库声明为vcs类型、url带.git后缀、repositories置于composer.json顶层，否则composer静默跳过；auth.json路径权限须正确、域名严格匹配；require包名须与私有库composer.json中name字段逐字符一致。
必须把私有 Git 仓库声明为 vcs 类型、URL 带 .git 后缀、repositories 放在 composer.json 顶层，否则 Composer 根本不会尝试克隆——它不报错，只是静默跳过。
repositories 必须是顶层数组且 type 明确为 "vcs"
Composer 只扫描 composer.json 最外层的 repositories 字段，嵌套在 config、extra 或任意自定义键下都无效。每项还必须显式写 "type": "vcs"，写成 "git"、"package" 或留空都会被忽略。
- ✅ 正确：
{"repositories": [{"type":"vcs","url":"https://gitlab.example.com/acme/utils.git"}]} - ❌ 错误：
"repositories": {"internal": {"url": "...", "type": "git"}}（对象格式 + type 错） - ❌ 错误：
"config": {"repositories": [...]}（嵌套在 config 下）
URL 必须可直接 git clone 且以 .git 结尾
Composer 不解析网页，只调用 git clone。任何不能直接粘贴进终端执行成功的地址，都会导致静默失败或 No valid composer.json was found 错误。
- ✅ 正确：
https://gitlab.example.com/acme/utils.git、git@gitlab.example.com:acme/utils.git - ❌ 错误：
https://gitlab.example.com/acme/utils（缺.git） - ❌ 错误：
https://gitlab.example.com/acme/utils/-/tree/main（HTML 页面地址） - 验证方式：在项目外手动运行
git clone https://your-url.git，成功才可能被 Composer 接受
auth.json 路径、权限和域名 key 必须严丝合缝
Composer 认证不走系统 Git 凭据，只读固定路径的 auth.json，且权限不对或域名不匹配时完全静默失效——不提示、不报错、不 fallback。
- 路径必须是：
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows） - 权限必须是
600：chmod 600 ~/.composer/auth.json，否则直接跳过 - 域名 key 必须与 URL host 完全一致：
"gitlab.example.com"≠"gitlab.example.com:8080"≠"https://gitlab.example.com" - GitLab 写法：
{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}
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 查
最容易被忽略的是：所有环节都依赖 host 名称的精确匹配——多一个端口、少一个子域、协议不一致，认证和源查找就断在第一环；而 Composer 对这些失败几乎不输出任何提示。
