多个GitLab实例必须用不同域名key隔离，Composer不做域名归一化，gitlab.example.com与gitlab.internal.org视为完全独立认证域，key必须与repositories.url的host部分严格一致（含端口），字段名必须为gitlab-token，值为含read_api和read_repository权限的Personal Access Token。
多个 GitLab 实例必须用不同域名 key 隔离
Composer 不做任何域名归一化，gitlab.example.com 和 gitlab.internal.org 是两个完全独立的认证域，哪怕它们指向同一台服务器。配错 key，token 就不会被加载。
常见错误是把多个实例都塞进 "gitlab.com" 下，或者写成 "https://gitlab.example.com"（带协议）——这些 key Composer 全部跳过。
- 每个自建 GitLab 实例的 key 必须和
repositories.url中的 host 部分严格一致：含端口就带端口（如"gitlab.example.com:8443"），不含端口就不带 - GitLab 官方托管用
"gitlab.com"；OAuth 场景才用"gitlab-oauth.gitlab.com"，二者不互通 - 不能复用同一个 token 到多个域名下，除非该 token 所属用户在所有目标项目中都有 Reporter 权限
auth.json 里 gitlab-token 字段名不能写错
字段名必须是 gitlab-token，不是 token、access_token、http-basic，也不是 gitlab.com.token。写错就等于没配。
正确结构是顶层对象内直接嵌套域名 key，值为一个含 gitlab-token 字段的对象：
{"gitlab.example.com": {"gitlab-token": "glpat-xxxxxxxxxxxxxxxxxxxx"}}
注意：gitlab-token 的值必须是 Personal Access Token，且权限必须同时勾选 read_api 和 read_repository；Deploy Token、CI_JOB_TOKEN、OAuth App Token 全部无效。
全局配置 vs 项目级 auth.json 的生效条件
Composer 只读两个位置的 auth.json：全局（~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）或项目根目录下的 ./auth.json。后者默认不生效，必须显式启用。
- Linux/macOS 全局路径必须是
~/.composer/auth.json，不是~/.config/composer/auth.json - 文件权限必须是
600（chmod 600 ~/.composer/auth.json），否则 Composer 静默忽略 - 项目级
./auth.json要生效，得配合COMPOSER_AUTH环境变量，或加--auth参数运行命令 -
composer config -g gitlab-token.gitlab.example.com xxx这类命令只对gitlab.com有效，自建站必须手动编辑auth.json
调试时怎么看 token 到底有没有被用上
运行 composer update -v，观察日志里是否有 Authorization: Bearer glpat- 请求头。没有就说明 token 没匹配上域名，或 auth.json 根本没被加载。
另一个快速验证法是跑：git ls-remote https://gitlab.example.com/group/pkg.git。如果它还弹用户名密码，说明 Git 层没通，Composer 必然也卡住——这时候要检查 git config --global credential.helper 是否设对（推荐 store 或 cache）。
容易被忽略的是：即使 token 正确、auth.json 位置正确，如果 composer.json 里没声明 "type": "vcs" 且 URL 不以 .git 结尾，Composer 根本不会尝试走 GitLab 认证流程。
