composer报“could not find package”主因是repositories未置顶层或缺"type": "vcs"，且require包名须与私有库composer.json中name字段严格一致，认证应通过auth.json（https）或deploy key（ssh）配置。
Composer报“Could not find package”时，先检查repositories是否在顶层且含type: "vcs"
这个错误90%不是认证问题，而是Composer根本没看到你的私有仓库。它不会自动扫描URL，必须显式声明源。
常见翻车点：
-
repositories被错放到config、scripts或require里，实际必须是composer.json最外层字段 - 只写了
"url": "https://gitlab.example.com/group/pkg.git"，却漏掉"type": "vcs" - URL用了网页地址（如
https://gitlab.example.com/group/pkg），缺.git后缀，GitLab CI下容易失败
正确写法示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/group/private-pkg.git"
}
],
"require": {
"group/private-pkg": "dev-main"
}
}
require里的包名必须和私有仓库composer.json中的name字段完全一致
Composer不按URL路径匹配，只严格比对name字段。大小写、斜杠方向、vendor名拼写，差一个字符就失败。
比如私有库根目录的composer.json里写的是：
{ "name": "myorg/utils", ... }
那主项目的require里就必须是"myorg/utils": "dev-main"，写成"MyOrg/utils"或"my-org/utils"都会报错。
顺带提醒：GitLab项目路径是group/subproject，不代表包名就是它——包名由其内部composer.json决定。
没有name字段的私有库，Composer会直接拒绝，不给任何提示。
HTTPS方式认证失败？别把Token硬编码进URL，用auth.json配http-basic
HTTPS URL里拼Token（如https://token:x-oauth-basic@...）已被弃用，且CI中极不稳定。正确做法是用auth.json统一管理凭据。
auth.json必须满足：
- 放在项目根目录（
./auth.json）或全局路径（~/.composer/auth.json） - 文件权限设为
600（chmod 600 auth.json） - 内容是标准JSON，
http-basic为顶层字段，不能嵌套
GitLab示例：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
Token需有read_repository权限；用户名填oauth2即可，不用真实账号。
SSH方式连不上？先确保ssh -T git@gitlab.example.com能通，再确认Deploy Key已绑定
SSH方式不走auth.json，全靠系统SSH配置。Composer只是调用git clone，所以本地能git clone git@gitlab.example.com:group/pkg.git成功，它才能成功。
关键检查点：
- 运行
ssh -T git@gitlab.example.com，看到Welcome to GitLab才算通 - 目标GitLab仓库已添加了你的公钥作为Deploy Key（不是账户SSH Key）
- 如果勾选了
Write access allowed，确保你真需要写权限；只读场景可不勾 - CI环境中注意：
composer.json里url的host必须和Deploy Key绑定的host完全一致
遇到Permission denied (publickey)，大概率是ssh-agent没加载密钥，或~/.ssh/known_hosts里缺少主机指纹（首次连接需手动确认）。
最常被忽略的一点：私有包的版本约束（如dev-main）只对应Git分支名，和它自己composer.json里的version字段无关。哪怕你改了version，Composer也完全不看。
