composer不支持全局gitlab-token键，仅识别auth.json中的http-basic（https克隆）和gitlab-token（gitlab api调用）两种格式；二者需按协议和用途分别配置，路径、权限、域名、token类型及权限缺一不可。
Composer 不支持直接配置 gitlab-token 这个键名的“全局开关”，它只认两种凭证格式：一种是 auth.json 里的 http-basic 块（用于 HTTPS），另一种是 gitlab-token 块（用于 GitLab API 调用）。填错位置、用错类型、权限不足，都会导致 composer install 卡在 “Could not fetch” 或报 401。
为什么 gitlab-token 在 auth.json 里不生效？
常见错误是把 gitlab-token 块写进了项目根目录的 composer.json，或者误以为只要写了 token 就自动生效。实际上：
-
auth.json必须放在正确路径：~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），项目根目录下的auth.json仅在当前项目生效，且优先级低于全局 -
gitlab-token块只用于 GitLab API 请求（比如获取项目信息、标签列表），不是用于git clone；如果你用的是 HTTPS URL 克隆，Composer 实际走的是 HTTP Basic Auth 流程，此时必须用http-basic块 - 域名必须完全匹配：如果仓库 URL 是
https://gitlab.example.com:8443/group/project.git，auth.json里就得写"gitlab.example.com:8443"，少端口或加/gitlab子路径都不行 - 文件权限必须是
600（Linux/macOS），否则 Composer 会静默忽略它
http-basic 和 gitlab-token 到底该用哪个？
取决于你 composer.json 中 repositories 的 URL 协议和用途：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 用 HTTPS 地址（如
"url": "https://gitlab.example.com/group/project.git"）→ 必须配http-basic块，username可填任意非空字符串（GitLab 忽略），password填glpat-xxxPersonal Access Token - 用 SSH 地址（如
"url": "git@gitlab.example.com:group/project.git"）→auth.json中的任何 token 都无效，必须靠系统 SSH 密钥，且要确保ssh -T git@gitlab.example.com能通 - 需要调用 GitLab API（比如解析
dev-main分支、读取子模块）→ 必须配gitlab-token块，否则即使克隆成功，也会在解析阶段失败 - 企业自建 GitLab 启用了双因素（2FA）→ HTTPS 方式只能用 PAT，不能用密码；SSH 方式不受影响
Token 权限和创建方式踩坑点
GitLab 的 token 类型和权限不是随便选的，填错就 401，但错误日志里往往只显示 “Could not fetch”，不提示缺哪项权限：
- 必须用 Personal Access Token（不是 Deploy Token、不是 CI Job Token、不是 Project Access Token），因为只有 PAT 支持 API 调用
- 权限至少勾选
read_repository；如果项目有子模块、或 Composer 需要获取 tags/branches 列表，还必须勾选read_api - Token 创建路径：用户头像 →
Settings→Access Tokens→ 填名称、过期时间、勾选权限 → 点Create personal access token→ 立刻复制保存（页面刷新后明文不可见） - 不要把 token 写进
composer.json或代码里，这是严重安全风险；也不要在 URL 里硬编码（如https://token:x-oauth-basic@gitlab.example.com/...）
验证配置是否真正生效
别只看 composer install 成功与否，很多问题在缓存或中间步骤就埋下了：
- 运行
composer diagnose，检查输出中是否有 “Authentication required” 或 “No auth config defined” 提示 - 加
-vvv参数重试：composer install -vvv，观察日志里是否出现Private-Token请求头（说明gitlab-token生效）或Authorization: Basic（说明http-basic生效） - 手动测试克隆：在终端执行
git clone https://gitlab.example.com/group/project.git，确认能拉下来——Composer 底层就是调这个命令 - 如果私有包还依赖其他私有包，所有上游仓库都得显式列在
repositories数组里，顺序无关，但一个都不能漏
最常被忽略的是：HTTPS 克隆走 http-basic，API 调用走 gitlab-token，两者经常要同时配；而很多人只配了一个，就以为万事大吉。
