GitLab个人访问令牌权限不足导致401，必须勾选read_api和read_repository；URL需用HTTPS完整地址并显式声明vcs类型；auth.json须置于项目根目录或全局路径，格式为标准JSON且username填oauth2、password填token。
GitLab 个人访问令牌权限不足导致 composer install 报 401
Composer 拉取私有 GitLab 仓库时提示 401 Unauthorized，大概率不是网络或 DNS 问题，而是令牌（Personal Access Token）缺少必要 scope。GitLab 的 token 必须显式勾选 read_api 和 read_repository，仅 api 或仅 read_user 都不够——Composer 在解析 composer.json 中的 "type": "git" 仓库时，会先调用 GitLab API 获取仓库元信息（如 latest commit、tags），再走 Git 协议克隆，两步都需对应权限。
实操建议：
- 重新生成 token，务必勾选
read_api+read_repository（write_repository非必需，除非你 push 包） - 确认 token 绑定的用户对目标项目有至少
Reporter权限（Guest不行） - 避免使用 Group Access Token——它不继承项目级权限，且 Composer 不支持其 bearer header 注入方式
composer.json 里写错仓库 URL 格式引发 404 或无限重定向
GitLab 私有仓库的 URL 写法直接影响鉴权路径。若用 HTTPS 形式但没带 token，Composer 默认走匿名请求；若用 SSH 形式却没配好 key，又会 fallback 到 HTTPS 并失败。更隐蔽的问题是：URL 域名和 GitLab 实例实际域名不一致（比如用了 CNAME 或内网地址），会导致 token 被发往错误 host，GitLab 拒绝校验。
实操建议：
- 统一用 HTTPS URL：
https://gitlab.example.com/namespace/project.git，不要省略.git后缀（Composer 依赖它识别 Git 类型） - 在
composer.json的repositories段中显式声明 type 为vcs，并指定url，不要依赖 Packagist 自动发现 - 验证 URL 可访问性：手动 curl -H "PRIVATE-TOKEN: xxx" "https://gitlab.example.com/api/v4/projects/namespace%2Fproject"，看是否返回 200
auth.json 配置位置或格式错误导致 token 不生效
Composer 查找 auth.json 的顺序是：当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer/auth.json）。如果放错位置，或 JSON 格式非法（比如多了一个逗号、用了单引号），token 就不会被加载，且 Composer 默认不报错，只静默回退到无鉴权模式。
实操建议：
- 优先放在项目根目录的
auth.json（与composer.json同级），内容必须是标准 JSON：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "your_personal_access_token_here"
}
}
}
-
username字段填oauth2是 GitLab 官方要求（不是你的用户名），password填 token 字符串本身 - 运行
composer config --global --list看是否显示http-basic配置已加载；或加-vvv参数执行composer install，观察日志里是否有Using HTTP basic authentication
GitLab Runner 或 CI 环境下 token 泄露与权限隔离问题
CI 流水线里硬编码 token 到 auth.json 或环境变量，容易被日志打印、缓存污染或误提交。更麻烦的是：Runner 使用的系统用户若没配置 Git 全局 credential helper，Composer 下载后触发的 git clone 步骤仍可能失败——因为 Composer 只负责 API 鉴权，Git 子进程另走一套凭据机制。
实操建议：
- CI 中用
COMPOSER_AUTH环境变量传入 base64 编码后的 auth.json 内容，而非文件落地（GitLab CI 支持 masked variables） - 在
.gitlab-ci.yml开头加git config --global credential.helper 'store'，再 echo 凭据到~/.git-credentials，确保后续 git 操作复用同一 token - 为 CI 专用 token 单独建一个最小权限用户，只授予目标项目的
Reporter角色，禁用sudo和 shell 登录
真正卡住人的往往不是 token 本身，而是 GitLab 的权限模型分层（API vs Git vs Project Role）和 Composer 的双阶段请求逻辑——漏掉任意一层，都会在不同环节报出看似相同的 401 或 404。
