gitlab私有源认证失败的典型表现是composer install/update提示401 unauthorized或反复弹出凭据框，根本原因是auth.json配置错误：域名未加https://前缀、路径不正确、gitlab-token字段未匹配仓库url，或composer.json中repositories缺少type:"gitlab"和正确的api v4地址。
GitLab私有源认证失败：token没生效的典型表现
运行 composer install 或 composer update 时提示 401 Unauthorized，或反复弹出 Git 凭据输入框，说明 Composer 根本没把你的 GitLab token 当作认证凭据用。这不是网络问题，是配置没落到关键位置——auth.json 没写对域名、没加协议头、或者被全局/项目级配置覆盖了。
auth.json 必须写对的三个细节
Composer 只认 auth.json 文件里的 http-basic 或 gitlab-token 字段，且必须严格匹配仓库域名。GitLab 私有源用的是 gitlab-token，不是 http-basic。
- 文件路径必须是
~/.composer/auth.json（全局）或项目根目录下的auth.json（仅当前项目） - 域名要带
https://前缀，且和composer.json里仓库的url完全一致（比如"url": "https://gitlab.example.com/api/v4"，那这里就得写"https://gitlab.example.com"） -
gitlab-token的值是 Personal Access Token，权限至少勾选read_api和read_repository；别错填成 CI_JOB_TOKEN 或 OAuth App token
正确示例：
{
"gitlab-token": {
"https://gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
composer.json 里仓库配置不能漏掉 type 和 url
只配 auth.json 不够，还得让 Composer 知道这个源是 GitLab 类型，否则它不会触发 gitlab-token 认证流程。
-
type必须设为gitlab（不是vcs或package） -
url必须是 GitLab API v4 地址，格式为https://gitlab.example.com/api/v4，结尾不加斜杠 - 如果用了自签名证书，得在
config里加"secure-http": false，否则会直接拒绝连接
示例片段：
"repositories": [
{
"type": "gitlab",
"url": "https://gitlab.example.com/api/v4"
}
]
调试 token 是否被读取：用 -v 参数看请求头
加 -v 运行命令，观察输出里有没有 Authorization: Bearer glpat-...。没有就说明 token 没匹配上域名，或 auth.json 路径不对。
- 执行
composer config --global --list查看是否误设了其他认证方式（比如http-basic覆盖了gitlab-token） - 检查
composer.json里有没有重复定义同域名仓库，导致优先级混乱 - Windows 下注意
~指向是否正确（通常是C:\Users\用户名\AppData\Roaming\Composer\auth.json）
真正卡住的地方往往不是 token 本身，而是域名拼写差一个字符、协议头少写 https://、或者 auth.json 放在了子目录里没被加载。
