私有 GitLab 仓库需在 composer.json 中声明为 "type": "vcs"，支持 HTTPS（需 Personal Access Token 配置 auth.json）或 SSH（需 deploy key 和 ssh-agent），并注意域名匹配、证书信任及 Rate Limit 等环境问题。
私有 GitLab 仓库必须声明为 repository 类型
Composer 默认只识别 packagist.org 上的包，要拉取私有 GitLab 仓库里的代码，必须在项目根目录的 composer.json 中显式声明该仓库为 vcs 类型。GitLab 仓库地址必须是 HTTPS 或 SSH 格式，且需确保 Composer 能访问（尤其是 HTTPS 地址要能通过认证）。
- HTTPS 地址示例：
"https://gitlab.example.com/your-group/your-package.git" - SSH 地址示例：
"git@gitlab.example.com:your-group/your-package.git" - 类型必须写成
"type": "vcs"，不能写"package"或漏掉 - 如果 GitLab 实例启用了子路径（如
/gitlab），URL 必须带完整路径，否则 Composer 无法解析 API
HTTPS 方式需配置 auth.json 并启用 GitLab Personal Access Token
GitLab 不支持 HTTP Basic Auth（用户名密码）直连，必须使用 Personal Access Token（PAT）。该 token 需具备 read_repository 权限，并写入本地 auth.json —— 注意不是项目级，而是用户级（~/.composer/auth.json 或 COMPOSER_HOME/auth.json）。
- token 必须放在
"http-basic"下，key 是 GitLab 域名（不含路径、端口、协议），例如："gitlab.example.com" - username 字段填任意非空字符串（GitLab 忽略它），password 字段填 PAT
- 若用自签名证书或内部 CA，需设置
"secure-http": false（仅限内网环境）或配置系统 CA 包
{
"http-basic": {
"gitlab.example.com": {
"username": "anything",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
SSH 方式依赖系统 ssh-agent 且需提前添加 deploy key
用 SSH 拉取比 HTTPS 更稳定，但前提是目标 GitLab 仓库已添加了当前用户的公钥作为 Deploy Key（勾选 Write access allowed 可选，只读场景可不勾），且本地 ssh-agent 已加载对应私钥。
- 检查是否生效：
ssh -T git@gitlab.example.com应返回 “Welcome to GitLab” - Composer 会自动调用系统
git命令，因此无需在auth.json中配置 SSH 凭据 - 若 CI 环境（如 GitLab CI）中使用 SSH，注意：默认
git clone使用的是CI_SERVER_URL解析出的域名，而非CI_REGISTRY；务必核对composer.json中 repository URL 的 host 是否与 deploy key 绑定的 host 一致
composer install 失败时优先排查 composer diagnose 和网络可达性
常见报错如 Could not fetch https://gitlab.example.com/api/v4/projects/... 或 Failed to download ... The "https://..." file could not be downloaded，往往不是配置写错，而是底层连接失败。
- 先运行
composer diagnose，重点看 “HTTP proxy support” 和 “GitHub API rate limit”（虽是 GitHub 提示，但 GitLab 同理）是否异常 - 手动执行
curl -H "PRIVATE-TOKEN: glpat-xxx" https://gitlab.example.com/api/v4/projects?search=your-package测试 API 是否通、token 是否有效 - 若用 Docker，确认容器内能解析并访问 GitLab 域名（
nslookup gitlab.example.com+ping -c2 gitlab.example.com） - GitLab 实例若启用了 Rate Limit，频繁调试可能触发限制，此时需等待或换 token
composer.json 写法，而在于 token 权限、DNS 解析、SSL 证书信任链、或 deploy key 是否绑定了正确的项目——这些点不逐个验证，光改配置没用。 
