Composer读取gitlab-token的唯一有效位置是auth.json，必须置于用户主目录（~/.composer/auth.json或%APPDATA%\Composer\auth.json），字段名为gitlab-token，域名key须与仓库URL host完全一致，且需配合composer.json中vcs类型仓库声明。
Composer 读取 gitlab-token 的唯一有效位置是 auth.json，且必须放在用户主目录（~/.composer/auth.json 或 %APPDATA%\Composer\auth.json），填错地方或字段名就完全无效。
auth.json 文件路径和结构必须严格正确
Composer 只在两个位置找 auth.json：全局（用户主目录）或项目根目录（需配合 COMPOSER_AUTH 环境变量）。项目级 ./auth.json 默认不生效。
-
auth.json必须是合法 JSON，顶层是对象，不能有尾随逗号 - 字段名必须是
gitlab-token（不是token、access_token或http-basic） - 域名 key 必须精确匹配仓库 URL 的 host 部分，不含协议、路径、端口（除非端口显式出现在 URL 中）；例如
gitlab.example.com:8080和gitlab.example.com是两个不同 key - 错误示例：
{"https://gitlab.com": {...}}、{"gitlab.com/api/v4": {...}}—— 这些 key Composer 直接忽略
gitlab-token 值必须是 Personal Access Token，且权限完整
Deploy Token、CI_JOB_TOKEN、OAuth App Token 全部不支持 API 调用，Composer 在获取包元数据阶段就会失败。
- Token 必须在 GitLab 用户 Settings → Access Tokens 页面创建
- 必须勾选
read_api（否则报403 Forbiddenon/api/v4/projects/）和read_repository（否则git clone失败） - 企业 GitLab 实例（如
gitlab.internal.org）上，该用户还需对目标项目有 Reporter 及以上权限 - 生成后立即复制保存——页面刷新后无法再次查看明文
composer.json 中必须声明 vcs 类型仓库
只配 auth.json 不够，Composer 不知道该向哪个地址发起 GitLab API 请求。它不会自动扫描所有已知域名。
-
repositories数组中必须包含"type": "vcs"条目 -
url必须是 HTTPS 格式的完整 Git 仓库地址，以.git结尾，例如："https://gitlab.example.com/group/lib.git" - 不能用 SSH 地址（如
git@gitlab...），否则跳过 token 认证流程 - 不能漏掉
require对应的包名，否则 Composer 根本不尝试访问该源
调试时看 -v 输出里的 Authorization 请求头
运行 composer update -v，观察日志中是否有类似 Authorization: Bearer glpat- 的请求头。没有就说明 token 没匹配上域名，或 auth.json 没被加载。
- 检查
composer config --global --list | grep gitlab，确认没被其他配置（如http-basic）覆盖 - 执行
git ls-remote https://gitlab.example.com/group/lib.git测试 Git 层是否通——如果也弹密码框，说明系统级凭据助手没配好，Composer 必然失败 - 缓存可能保留旧的 401 响应，务必运行
composer clear-cache再试
最容易被忽略的是：域名匹配必须一字不差，包括端口；gitlab-token 字段不能嵌套在 http-basic 下；以及 vcs 声明是强制前提——三者缺一，token 就等于没写。
