repositories必须写在composer.json顶层，type必须为"vcs"，url须为含.git后缀的可clone地址；auth.json需置于~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），权限600，内容按域名严格匹配；require包名须与私有库composer.json中name字段逐字符一致；启用私有源后须显式添加packagist.org并设"packagist": false以恢复公共包安装。
repositories 必须写在 composer.json 顶层，且 type 必须是 "vcs"
Composer 不会扫描嵌套结构里的 repositories，比如放在 config、scripts 或任意自定义字段下都无效。它只认最外层的数组。
常见错误包括：
-
"type": "git"或"type": "package"—— 必须写"type": "vcs"，否则静默忽略 -
"url": "https://gitlab.example.com/acme/utils"—— 缺.git后缀，git clone会失败，Composer 也拒绝识别 -
"url": "https://gitlab.example.com/acme/utils/tree/main"—— 这是网页地址，不是 Git 协议地址
正确写法示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/acme/utils.git"
}
],
"require": {
"acme/utils": "dev-main"
}
}
auth.json 放错位置或权限不对，Composer 就当没这回事
Composer 只读取固定路径的 auth.json，且必须是用户级配置，不是项目级的。项目根目录下放 auth.json 完全无效。
路径必须是：
- Linux/macOS：
~/.composer/auth.json - Windows：
%APPDATA%\Composer\auth.json
权限必须设为 600（仅所有者可读写），否则 Composer 直接跳过：
chmod 600 ~/.composer/auth.json
内容结构要严格匹配 GitLab 域名和认证方式：
- 用 HTTPS + Token：必须用
http-basic字段，username固定为oauth2，password是glpat-开头的 Personal Access Token - 域名 key 必须和
repositories.url的 host 完全一致（不含协议、端口、路径），例如gitlab.example.com:8080和gitlab.example.com是两个不同 key
正确示例：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
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"❌（不是同一个 name） -
"utils"❌（缺 vendor 段） -
"acme/utils": "main"❌（没dev-前缀，会被当成模糊约束去 Packagist 查）
如果私有库没打任何 tag，唯一能用的版本就是 dev-main（或 dev-master，取决于默认分支名）。
加了私有源后，Packagist 默认被关掉，得手动补上
只要你在 repositories 数组里加了一条 vcs，Composer 就会默认禁用隐式的 Packagist 源。结果就是：私有包找不到，公共包也装不上。
解决方法是在 repositories 数组里显式加一条 Packagist 条目，并设 "packagist": false：
{
"repositories": [
{ "type": "vcs", "url": "https://gitlab.example.com/acme/utils.git" },
{ "type": "composer", "url": "https://packagist.org", "packagist": false }
]
}
注意顺序：把私有源放前面，Packagist 放后面，避免路由混乱。别依赖 composer config -g repositories，项目级 composer.json 会完全覆盖全局配置。
验证是否真正可达，最简单的方法是手动执行：
git ls-remote -h https://gitlab.example.com/acme/utils.git
能列出分支才算通。否则别急着 composer install，先修 Git 层。
