repositories必须是顶层数组且type必须为"vcs"，否则Composer静默忽略；url须为可git clone地址（如https://gitlab.example.com/acme/utils.git），缺.git后缀或写成网页地址均导致失败。
repositories 字段必须是顶层数组，且 type 必须为 "vcs"
Composer 不会自动扫描你的 GitLab 实例，repositories 必须写在 composer.json 最外层，不能嵌套在 config、scripts 或其他字段里。否则 Composer 完全忽略它。
每项私有仓库必须显式声明 "type": "vcs" —— 写成 "git"、"package"、"gitlab" 或留空，都会被静默跳过，不报错也不拉取。
-
url必须是能直接git clone的地址：HTTPS 格式如https://gitlab.example.com/acme/utils.git，SSH 格式如git@gitlab.example.com:acme/utils.git - 缺
.git后缀（例如写成https://gitlab.example.com/acme/utils）会导致No valid composer.json was found - 多个私有库就写多个对象，顺序无关，但建议把最常用的那个放前面
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，否则直接忽略 - GitLab 必须用
http-basic字段，结构为：{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}} - 域名 key（如
gitlab.example.com）必须和repositories.url中的 host 完全一致，不含协议、端口、路径；gitlab.example.com:8080和gitlab.example.com是两个不同 key
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"或"*"会被当成模糊约束，去 Packagist 查，查不到就失败 - 如果私有库没打任何 tag，唯一可用版本就是
dev-main（或dev-master，取决于默认分支名）
HTTPS 连 GitLab 时 secure-http 配置容易被忽略
如果你的 GitLab 实例用的是自签名证书、HTTP 协议、或非标准端口（如 http://gitlab.internal:8080），默认会因 secure-http 强制启用而失败。
- 临时允许非 HTTPS：
composer config -g secure-http false，或在项目composer.json的config下加"secure-http": false - 但注意：一旦开了
secure-http: false，所有 HTTPS 请求也会降级走 HTTP，可能触发 GitLab API 的404 Project Not Found（因为 Composer 自动拼了/api/v4/projects/...路径） - 更稳妥的做法是用 SSH + 密钥，避免 HTTP 认证和证书问题；或者确保 GitLab 启用了有效的 TLS 证书
最容易被漏掉的是三件事：repositories 没放顶层、auth.json 权限不是 600、私有库 composer.json 的 name 和 require 里的不完全一致——这三处出错，Composer 都不会明确告诉你哪里错了，只会安静地失败。
