Composer不支持composer config gitlab-token命令，gitlab-token仅能配置在~/.composer/auth.json中，格式为{"gitlab-token":{"gitlab.example.com":"glpat-..."}}，且需同时具备read_api和read_repository权限。
直接结论：不要用 composer config gitlab-token 这个命令——它根本不存在，Composer 不识别这个配置项，执行后只会静默失败或报错“unknown setting”。
gitlab-token 不是 Composer 的合法 config key
Composer 的 config 命令只支持预定义的键（如 http-basic、github-oauth），但 gitlab-token 是一个auth.json 文件结构字段，不是全局配置项。你运行 composer config --global gitlab-token.gitlab.example.com xxx，Composer 会把它当成一个普通配置写进 config.json，完全不会生效。
- 真正起作用的是
~/.composer/auth.json中的"gitlab-token"对象，格式必须为：{"gitlab-token": {"gitlab.example.com": "glpat-..."}} -
composer config --global gitlab-token.xxx是社区误传的“快捷命令”，实际是某些脚本或旧版插件伪造的行为，官方 Composer 从不解析gitlab-token开头的 config key - 验证方式：执行
composer config --global --list | grep gitlab，如果输出为空，说明没写进去；即使有，也属于无效配置
正确写入 gitlab-token 的两种可靠方式
必须把 token 放进 auth.json，且位置、权限、格式三者缺一不可：
- 路径必须是
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），不能放项目目录下 - 文件权限必须设为
600（Linux/macOS）：chmod 600 ~/.composer/auth.json，否则 Composer 拒绝读取 - 域名必须与仓库 URL 的 host 部分完全一致：比如仓库 URL 是
https://gitlab.example.com:8443/group/pkg.git，key 就得是"gitlab.example.com:8443"，多一个斜杠、少一个端口都不行 - 推荐用
composer config --global --auth gitlab-token.gitlab.example.com glpat-xxx—— 注意这里用了--auth标志，它会自动写入auth.json正确结构，而不是config.json
为什么 auth.json 里写 http-basic 会失败
GitLab 不接受 HTTP Basic Auth 形式的用户名/密码组合，它只认 Personal Access Token 并要求以 Authorization: Bearer 方式传递。而 http-basic 配置强制走 username:password Base64 编码，GitLab 会直接返回 401 Unauthorized。
- 错误示例：
{"http-basic": {"gitlab.example.com": {"username": "token", "password": "glpat-..."}}}→ 一定失败 - 正确示例：
{"gitlab-token": {"gitlab.example.com": "glpat-..."}}→ 才能触发 Composer 内部的 Bearer header 注入逻辑 - Deploy Token、CI_JOB_TOKEN、项目级 token 全部不支持
gitlab-token流程，只认用户级 Personal Access Token，且必须勾选read_api和read_repository
常见失败信号和快速验证点
遇到 Could not fetch 或 Failed to clone 时，别急着重试，先检查这几个硬性条件是否满足：
- 运行
git ls-remote https://gitlab.example.com/group/pkg.git：如果弹出用户名密码，说明 Git 层凭证没通，Composer 必然失败 - 检查
composer.json的repositories是否为"type": "vcs"，且"url"以.git结尾（漏掉会走 API 下载 ZIP，私有库默认禁用） - 确认包名（
require里的vendor/name）和 GitLab 项目根目录composer.json中的"name"字段逐字符一致（大小写、斜杠、vendor 名全部敏感） - 运行
composer install -vvv，看日志里是否出现Using GitLab token for gitlab.example.com—— 没这句就说明 token 没加载成功
最易被忽略的是：token 权限必须同时包含 read_api（查元数据）和 read_repository（克隆代码），缺一不可；而错误日志里通常只报 403 或 401，不提示具体缺哪个 scope。
