连不上公司 GitLab 私有库，90% 是因 auth.json 路径错误（仅认项目根目录或全局 ~/.composer/auth.json）、域名 key 未与 repositories.url 主机名完全一致（如不能含协议/路径）、字段名误用（必须为 gitlab-token，非 http-basic 等），或 composer.json 缺少 type:"vcs" 和正确 .git 结尾的 HTTPS url。
连不上公司 GitLab 私有库，90% 是因为 auth.json 没配对位置、域名或字段名，或者 composer.json 里漏了 vcs 声明——不是网络问题，也不是 Token 本身无效。
auth.json 必须放对路径、字段名和域名格式
Composer 只在两个地方读 auth.json：全局（~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）或项目根目录（但需配合 COMPOSER_AUTH 环境变量）。放在 vendor/ 或子目录下完全无效。
-
gitlab-token是唯一有效的字段名，写成token、access_token或http-basic都不生效 - 域名 key 必须是纯 host，不含协议、路径、端口（除非 URL 显式带端口），例如
"gitlab.example.com:8080"和"gitlab.example.com"是两个独立 key - 错误示例：
{"https://gitlab.example.com": {...}}或{"gitlab.example.com/api/v4": {...}}—— Composer 直接跳过 - 文件权限必须是
600：chmod 600 ~/.composer/auth.json，否则 Composer 会静默忽略
Token 权限必须同时开 read_api 和 read_repository
GitLab 的 Personal Access Token 不是“开了 API 就能用”。Composer 在安装时分两步走：先调 /api/v4/projects/ 查元数据（需要 read_api），再执行 git clone --mirror 拉代码（需要 read_repository）。缺一不可。
- 只勾
api→ 报403 Forbiddenon/api/v4/projects/ - 只勾
read_repository→ 报Failed to download ... git clone --mirror - Deploy Token、CI_JOB_TOKEN、OAuth App Token 全部不支持 API 调用，第一步就卡死
- 企业实例上，该 Token 所属用户还必须对目标项目有 Reporter 及以上权限
composer.json 必须显式声明 vcs 类型仓库
只配 auth.json 不够。Composer 不会自动扫描你访问过的 GitLab 域名，它只认你明确定义的源。
-
repositories必须是顶层字段，不能嵌套在config或scripts下 - 每条仓库配置必须含
"type": "vcs"，写成"type": "package"或漏掉这一行，Composer 当它不存在 -
url必须是 HTTPS 地址、以.git结尾，例如："https://gitlab.example.com/group/lib.git" - 不能用 SSH 地址（如
git@gitlab...），否则跳过 token 认证流程 - require 的包名必须和私有库
composer.json中的name字段逐字符一致，大小写、斜杠方向都不能错
调试时看 -v 日志里的 Authorization 请求头
运行 composer update -v，观察输出中是否有类似 Authorization: Bearer glpat- 的请求头。没有，说明要么 auth.json 没加载，要么域名 key 没匹配上。
- 用
composer config --global --list | grep gitlab检查是否被其他配置（如http-basic）覆盖 - 用
git ls-remote https://gitlab.example.com/group/lib.git单独测试 Git 层是否通——如果也弹用户名密码，说明系统级 credential helper 没配好，Composer 必然失败 - 自建 GitLab 实例若启用了子路径（如
/gitlab），url中也得带上，否则 API 请求 404
最容易被忽略的是：Token 权限必须双开、auth.json 域名 key 必须和 repositories.url 的 host 完全一致、name 字段必须逐字符匹配——三者缺一，Composer 就当这个包不存在，连报错都懒得给。
