必须同时满足：repositories 显式声明为 vcs 类型、URL 以 .git 结尾、认证信息正确注入；缺一则报“Could not fetch”或“Could not find package”，因 Composer 仅查询 packagist.org 和 repositories 中合法声明的源，且包名、分支/标签、权限等须严格匹配。
Composer 要拉到 GitLab 私有仓库的包，必须同时满足三个硬性条件：repositories 显式声明为 vcs 类型、URL 以 .git 结尾、认证信息正确注入。缺一不可，否则会卡在 Could not fetch 或 Permission denied。
为什么加了 repositories 还是报 “Could not find package”
这不是网络问题，而是 Composer 根本没去你的 GitLab 查——它只查 packagist.org 和你 repositories 里明确列出的源。常见原因包括：
-
repositories声明顺序错误：私有源必须放在packagist.org之前，否则被跳过（可加"packagist.org": false彻底禁用） - 包名不一致：require 中写的
"myorg/internal-sdk"必须和 GitLab 项目根目录composer.json里的"name"字段完全一致（大小写、斜杠、vendor 名都敏感） - URL 不合法：漏掉
.git后缀（GitLab 15+ 强制校验）、用了 Web 页面 URL（如https://gitlab.example.com/group/project）而非克隆地址 - 分支/标签没显式指定：
"myorg/internal-sdk": "^1.0"会去 Packagist 查，必须写成"myorg/internal-sdk": "dev-main"或"v2.1.0"
HTTPS 方式怎么配 Token 才不 401
GitLab 不接受 HTTP Basic Auth 的用户名密码组合，只认 Personal Access Token（PAT）或 Deploy Token，并且必须通过特定方式传递：
One-click installation of GitHub projects
下载
GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。
- Token 必须有
read_repository权限（read_package_registry没用） - 不能塞进
auth.json的http-basic下——那是给 SVN 或旧版私有 Packagist 用的 - 正确位置是
auth.json的gitlab-token键下，结构为：{ "gitlab-token": { "gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx" } } - 更安全的做法是用环境变量：
COMPOSER_AUTH='{"http-basic":{"gitlab.example.com":{"username":"deploy-token-123","password":"abc456def789"}}}'（Deploy Token 场景） - 本地调试时可用
composer config --global gitlab-token.gitlab.example.com <token>，自动处理格式和权限
SSH 方式为什么 clone 失败
SSH 不走 auth.json，完全依赖系统 SSH 配置，失败通常是因为链路断在中间某环：
- GitLab 项目没添加 Deploy Key（或用户 SSH Key），且未勾选
Write access allowed（只读可不勾） - 本地
ssh-agent没加载对应私钥：ssh-add -l看是否列出，没列就ssh-add ~/.ssh/id_rsa - 测试连通性必须用
ssh -T git@gitlab.example.com，返回Welcome to GitLab才算通 -
composer.json中url必须是标准 SSH 格式："git@gitlab.example.com:group/project.git"，不能混用 HTTPS 域名 - CI 环境中注意
CI_SERVER_URL解析出的域名是否和 Deploy Key 绑定的 host 完全一致（比如带端口或子域）
为什么 composer install 总是走 API 下载 zip 而不是 clone
因为没声明 "type": "vcs"，Composer 默认把所有 HTTPS URL 当作 dist 源处理，试图调 GitLab API 下载 /archive.zip——而私有库默认关闭该 API 匿名访问。
- 必须显式写
"type": "vcs"，强制走git clone流程，后续才能注入 Token 或走 SSH - Deploy Token 只支持 HTTPS 协议，不能用于 SSH；若要用，得拼进 URL：
"https://deploy-token-123:abc456def789@gitlab.example.com/group/project.git" - 但硬编码 Token 到
composer.json是高危操作，CI 中应通过 secret 注入auth.json或用COMPOSER_AUTH - 确认
~/.composer/auth.json权限是600，否则 Composer 直接忽略该文件
最容易被忽略的是：私有包自身如果也依赖其他私有包，所有上游仓库都得列在当前项目的 repositories 里，不能指望“递归发现”。认证、协议、命名、版本约束，四者任一错位，就会静默失败。
