多个私有gitlab仓库可共存，但需每项显式声明"type": "vcs"、url带.git后缀，且各域名认证信息须严格按格式配置在auth.json中；漏配任一环节均导致静默失效。
多个私有 GitLab 仓库能同时用，但必须每条 repositories 项都显式声明 "type": "vcs"、带 .git 后缀的可克隆地址，并且每个域名对应的认证信息要单独配在 auth.json 里——漏一条，那一整个仓库就静默失效。
repositories 数组里怎么写多个 GitLab 源才不被忽略
Composer 不会自动推断你写了多个 Git 地址就“都生效”，它只逐条检查每项是否符合 VCS 规则。常见错误是把两个 URL 塞进一个对象、或漏掉 "type": "vcs"。
-
"type"必须是"vcs"，不是"git"、"package"或空着 -
"url"必须是能直接git clone的地址，例如https://gitlab.example.com/acme/utils.git或git@gitlab.example.com:acme/sdk.git - 不能写成网页地址（如
https://gitlab.example.com/acme/utils）、也不能写成 release 页面（如https://gitlab.example.com/acme/utils/-/releases/v1.0） - 多个源之间无隐式优先级，顺序只影响 Composer 查包时的尝试次序；若包名冲突，以第一个匹配到的为准
auth.json 怎么支持多个 GitLab 域名
一个 auth.json 文件可以管多个域名，但结构必须严格按 http-basic 下嵌套 key-value 对，每个 key 是纯域名（不含协议、端口、路径），且大小写、端口都要完全一致。
- Linux/macOS 路径必须是
~/.composer/auth.json，Windows 是%APPDATA%\Composer\auth.json - 权限必须设为
600：运行chmod 600 ~/.composer/auth.json，否则 Composer 直接跳过读取 - 示例合法结构：
{ "http-basic": { "gitlab.example.com": { "username": "oauth2", "password": "glpat-xxx1" }, "gitlab.internal.company": { "username": "oauth2", "password": "glpat-xxx2" } } } - 如果用了端口（如
gitlab.example.com:8080），那auth.json里也得写成"gitlab.example.com:8080"，少一个字符都不认
require 包名和分支写法为什么总报 “Could not find package”
报这个错，90% 不是网络或权限问题，而是包名没对上、或分支没加 dev- 前缀——Composer 完全不模糊匹配，差一个字母、大小写、下划线，就当不存在。
- 私有库根目录的
composer.json里写的"name"字段，必须和主项目require里的键**完全一致**，例如"acme/utils"≠"Acme/utils"≠"acme-utils" - 分支名必须加
dev-前缀："dev-main"可行，"main"或"*"会被当成语义化版本约束，去 Packagist 查，查不到就失败 - 如果私有库没打任何 tag，唯一可用的版本就是
"dev-main"（或"dev-master"，取决于默认分支名） - 别依赖全局
composer config -g repositories；项目级composer.json的repositories会完全屏蔽全局配置
为什么加了 repositories 还是去 Packagist 查包
因为加了任意一条 vcs 源后，Composer 默认关闭 packagist.org 的隐式源——它不会“顺手查一下官方源”，除非你明确告诉它“这个包该去哪找”。
- 必须在
repositories数组里**显式补一条 Packagist 兜底项**：{"type": "composer", "url": "https://packagist.org", "packagist": false} - 更稳妥的做法：把私有源放数组最前面，兜底项放最后，确保路由可控
- 验证是否生效：运行
composer config --list | grep repositories，确认看到所有源，包括 Packagist 那条 - 别信“删掉 repositories 就恢复官方源”——不加兜底项，哪怕只留一个私有源，也会导致其他非私有包找不到
真正卡住的地方往往不是语法，而是 auth.json 权限不对、域名大小写不一致、URL 缺 .git、或者忘了补 Packagist 兜底——这些都不会报错，只会静默跳过。建议每次改完先跑 git ls-remote -h https://gitlab.example.com/acme/utils.git 确认可达，再试 composer require。
