GitLab token必须写入auth.json且字段名、域名、权限三者全对才生效；路径为~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），域名需带https://前缀并精确匹配仓库URL，权限须含read_api和read_repository。
GitLab token 必须写进 auth.json，且字段名、域名、权限三者全对才生效；填错任意一项，composer install 都会卡在 401 或反复弹密码框。
auth.json 路径和结构必须严格匹配 Composer 查找规则
Composer 只在两个地方找 auth.json：全局（用户主目录）或项目根目录（需配合 COMPOSER_AUTH 环境变量）。项目级的 ./auth.json 默认不加载，很多人放错位置导致 token 完全没被读取。
- Linux/macOS 全局路径：
~/.composer/auth.json（不是~/.config/composer/auth.json） - Windows 全局路径：
%APPDATA%\Composer\auth.json -
auth.json必须是合法 JSON，顶层是对象，不能有尾随逗号 - 字段名必须是
gitlab-token（不是token、access_token或http-basic） - 域名 key 必须精确匹配仓库 URL 的 host 部分，含协议和端口（如
"https://gitlab.example.com:8080"），不含路径、用户、查询参数
gitlab-token 域名 key 写错就等于没配
Composer 对域名 key 的匹配极其严格，任何格式偏差都会导致整段配置被忽略。它不解析 URL，只做字符串完全匹配。
- ✅ 正确示例：
"https://gitlab.com"、"https://gitlab.example.com"、"https://gitlab.example.com:8443" - ❌ 错误示例：
"gitlab.com"（缺协议）、"https://gitlab.com/api/v4"（多路径）、"git@gitlab.com"（SSH 格式）、"https://gitlab.com/"（末尾斜杠） - 多个 GitLab 实例要分开写：
"https://gitlab.com"和"https://gitlab.internal.org"是两个独立 key，不能合并 - 如果用自签名证书，还需在
composer.json的config段加"secure-http": false，否则请求直接失败
Personal Access Token 权限缺一不可
Token 类型和 scope 必须精准对应 Composer 的两阶段行为：先调 API 获取元数据，再走 Git 协议克隆代码。少一个权限，就会在不同阶段报错。
- 必须是 Personal Access Token（不是 Deploy Token、CI_JOB_TOKEN 或 OAuth App Token）
- 必须勾选
read_api（否则403 Forbidden on /api/v4/projects/） - 必须勾选
read_repository（否则Failed to execute git clone --mirror） - 企业 GitLab 实例上，该用户还需对目标项目有 Reporter 及以上权限（Guest 不行）
- 生成后立即复制保存——页面刷新后无法再次查看明文
composer.json 中 repositories 必须声明 vcs 类型 HTTPS 地址
只配 auth.json 不够。Composer 不会自动扫描所有已知域名，它需要明确知道“这个包从哪来”，才会触发 token 认证流程。
-
type必须是"vcs"（不是"package"或"path"） -
url必须是完整 HTTPS Git 地址，以.git结尾，例如："https://gitlab.com/group/lib.git" - 不能用 SSH 地址（如
git@gitlab.com:group/lib.git），否则跳过 token 认证 - 必须在
require中声明对应包名，否则 Composer 根本不尝试访问该源 - 调试时加
-v运行composer update，观察日志中是否有Authorization: Bearer glpat-请求头；没有就说明 token 没匹配上或没加载
最容易被忽略的是域名 key 的协议部分——很多人以为 gitlab.com 就够了，结果一直 fallback 到交互式认证。实际必须带 https:// 前缀，且和 composer.json 中仓库 URL 的协议、host、端口逐字节一致。
