GitLab私有令牌必须配置在auth.json中而非composer.json里，因Composer禁止硬编码凭证；项目级需放根目录、全局级为~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），权限设600，格式为{"gitlab-token":{"gitlab.example.com":"glpat-xxx"}}，域名须与仓库URL host完全一致，且Token需含read_api和read_repository权限。
GitLab 私有令牌必须用 auth.json 而不能写在 composer.json 里
Composer 不允许在 composer.json 中硬编码凭证，否则会报错 Invalid credentials given for repository 或直接忽略认证。正确路径是项目根目录（或全局 COMPOSER_HOME）下的 auth.json 文件。
该文件需手动创建，且权限必须严格（chmod 600 auth.json），否则 Composer 会拒绝读取并静默跳过认证。
-
auth.json格式必须为 JSON 对象，顶层键只能是http-basic或gitlab-token - GitLab 私有令牌应放在
gitlab-token下，不是http-basic—— 后者只用于 Basic Auth（如自建 Git 仓库），而 GitLab API 认证走的是Private-TokenHeader - 令牌值必须是 Personal Access Token，且至少勾选
read_api和read_repository（如果要 clone 私有包）
配置 gitlab-token 的具体写法和位置
有两种生效范围：项目级（推荐）和全局级。项目级更安全，避免泄露到其他项目。
项目级：在项目根目录新建 auth.json，内容如下：
{
"gitlab-token": {
"gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
注意：gitlab.example.com 必须与 composer.json 中仓库 URL 的 host 完全一致（比如用 git@gitlab.example.com 或 https://gitlab.example.com 都算同一 host）；若用子路径（如 https://gitlab.example.com/group），仍只需填域名部分。
- 全局配置路径通常是
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows） - 多个 GitLab 实例可共存，每个 domain 单独一行，不要合并成数组
- 令牌字符串不能带换行、空格或引号外的特殊字符
为什么 composer install 还是提示 401？常见校验点
即使 auth.json 存在且格式正确，仍可能因以下原因失败：
- Composer 版本低于 2.2 ——
gitlab-token支持从 v2.2 开始引入，旧版会完全忽略该字段 - GitLab 域名拼写错误，比如多了一个
www.或少了一个.com，导致匹配失败 - 令牌已过期或被 revoke，但 Composer 不报具体原因，只会返回
Failed to download ... 401 Unauthorized - 仓库 URL 在
composer.json中用了git+ssh协议（如git@gitlab.example.com:group/pkg.git），此时gitlab-token不生效——SSH 认证走的是 SSH key，不是 Token
验证是否生效：运行 composer config --list --global（或去掉 --global 查项目级），确认输出中包含 gitlab-token 条目；再执行 composer diagnose，它会检查 auth.json 权限和语法。
镜像场景下如何让私有 GitLab 包走指定镜像源
Composer 本身不支持“镜像认证”，所谓“GitLab 镜像”实际是把私有包托管在另一个 GitLab 实例上，或通过 repositories 手动声明类型为 vcs 的源。此时认证仍走 auth.json 中对应域名的 gitlab-token。
关键点在于：镜像域名 ≠ 原始域名。例如原始包在 gitlab.company.com，你把它同步到了 gitlab-mirror.internal，那么 auth.json 里必须配后者，而不是前者。
- 如果镜像使用反向代理统一入口（如
mirror.example.com），则所有包都走这个域名，auth.json只需配这一个 - 不能靠
config repo-cache或config cache-dir解决认证问题——这些只影响本地缓存路径，不参与 HTTP 请求头构造 - CI 环境中建议用环境变量注入令牌（如
COMPOSER_AUTH），但值必须是 base64 编码的完整auth.json字符串，且仍受权限和版本限制
最易被忽略的是：GitLab 实例启用了双因素认证（2FA）时，Personal Access Token 是唯一可行方式，SSH key 或 Web IDE 登录态均无效。
