Composer install 报 401 Unauthorized 是因未配置 GitLab OAuth 令牌；需生成含 read_api 和 read_repository 权限的令牌，并在 auth.json 中用 "gitlab-token" 类型配置对应域名。
为什么 composer install 会报 401 Unauthorized？
当你在 composer.json 中引用了 GitLab 私有仓库（比如 "git@gitlab.example.com:group/project.git" 或 "https://gitlab.example.com/group/project.git"），Composer 默认不会携带认证凭据。SSH 方式需配置密钥，HTTPS 方式则依赖 Git 凭据或 Composer 的 auth.json。OAuth 令牌是 HTTPS 场景下最可控、最易集成 CI/CD 的方式——但必须确保它被正确注入且权限足够。
如何生成并配置有效的 GitLab OAuth 令牌？
GitLab 的 OAuth 令牌需具备 read_api 和 read_repository 权限（api 范围不足以拉取代码）。仅用 read_api 会导致 403 Forbidden；若用 api + sudo 则过度授权，不推荐。
- 登录 GitLab → Settings → Access Tokens → 填写名称，勾选
read_api和read_repository - 复制生成的令牌（只显示一次，务必立刻保存）
- 该令牌不能用于 Git SSH，仅适用于 HTTPS 协议的仓库地址
如何让 Composer 在拉取时自动使用这个令牌？
核心是让 Composer 把令牌注入到 HTTPS 请求头中。GitLab 要求在 Authorization 头中传 Bearer ，而 Composer 本身不直接支持 Bearer 认证——它依赖 http-basic 配置，但 GitLab 的 OAuth 令牌不兼容传统用户名/密码模式。因此必须启用 gitlab-token 类型配置：
{
"gitlab-token": {
"gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
把这个 JSON 写入 auth.json 文件。位置优先级：项目根目录下的 auth.json > COMPOSER_HOME/auth.json（通常是 ~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）。
- 确保
auth.json文件权限为600（Linux/macOS），避免被其他用户读取 - 域名必须完全匹配仓库 URL 的 host 部分（如
gitlab.example.com，不含https://或路径） - 如果使用自签名证书的 GitLab 实例，还需额外设置
"secure-http": false（不推荐生产环境）
验证是否生效：常见失败信号与排查点
运行 composer install -vvv 可看到详细请求日志。若仍失败，重点检查以下几点：
- 错误信息含
Failed to clone https://...+401：令牌未配置，或域名拼写不一致（比如用了www.gitlab.example.com但配置的是gitlab.example.com） - 错误含
403：令牌权限不足（缺read_repository），或该令牌已被吊销/过期 - 错误含
Could not authenticate against gitlab.example.com：Composer 版本太低（2.2+才完整支持gitlab-token） - CI 环境中变量注入失败：不要硬编码令牌，应通过环境变量 +
auth.json模板生成（例如 GitHub Actions 中用jq动态写入）
GitLab 私有包的认证链条比想象中更脆弱：令牌权限、域名匹配、Composer 版本、文件权限、协议类型（HTTPS vs SSH）任一环出错都会中断安装。最容易忽略的是——你以为配对了，其实只是域名少了个子域，或者令牌没勾选 read_repository。
