根本原因是composer默认不带认证凭据访问gitlab私有仓库，必须用含read_api和read_repository权限的personal access token（pat）并通过auth.json正确配置http-basic，域名、用户名、密码、权限四者缺一不可。
GitLab私有包为什么总是 401 Unauthorized？
根本原因是 Composer 默认不带认证凭据去拉取私有仓库，哪怕你本地 git clone 能通，Composer 也走的是另一套 HTTP 认证逻辑。GitLab 不接受密码直传，必须用 Personal Access Token（PAT），且该 token 必须带 read_api 和 read_repository 权限。
常见错误现象：Could not fetch https://gitlab.example.com/api/v4/projects/123 或 Failed to download vendor/package: 401 Unauthorized —— 这不是网络问题，是认证缺失。
- 别用 GitLab 账号密码填在
auth.json里，GitLab 已弃用密码认证 - token 必须在 GitLab 用户设置 → Access Tokens 页面生成，不能用项目级 deploy token（它不支持 API 调用）
- 生成后立即复制保存，页面刷新后无法再次查看明文
如何正确配置 auth.json 支持 GitLab 私有包？
Composer 通过全局或项目级 auth.json 注入 HTTP Basic Auth 头，把 PAT 当作密码、用户名填 gitlab.example.com（注意：不是邮箱，也不是任意字符串）。
推荐放在项目根目录下，避免污染全局配置：
{
"http-basic": {
"gitlab.example.com": {
"username": "gitlab.example.com",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
-
username字段值必须和仓库 URL 的 host 一致，比如gitlab.company.internal就填那个完整域名 -
password填完整的 token（含glpat-前缀），别漏掉 - 文件权限必须是
600（chmod 600 auth.json），否则 Composer 会拒绝读取 - 如果用
composer config --auth http-basic.gitlab.example.com ...命令生成，它会自动处理格式和权限
composer.json 中怎么声明 GitLab 私有包？
关键在于 repositories 配置要匹配 GitLab 项目路径，并指定 vcs 类型；同时确保包名与 GitLab 项目命名空间一致。
示例（假设 GitLab 地址为 https://gitlab.example.com，项目路径为 my-group/my-package）：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/my-group/my-package.git"
}
],
"require": {
"my-group/my-package": "^1.0"
}
}
- URL 必须以
.git结尾，否则 Composer 无法识别为 Git 仓库 - 包名
my-group/my-package必须和 GitLab 项目「Group/Project」路径完全一致（区分大小写） - 如果项目启用了子组（如
my-group/subgroup/my-package），包名也要带斜杠，不能扁平化 - 不要加
https://前缀到包名里 —— Composer 不认这种写法
为什么 composer install 仍拉不到最新 tag？
GitLab 默认不暴露 tags 列表给未认证请求，即使 auth.json 配置正确，Composer 也可能因缓存或 Git 配置跳过远程更新。
- 执行
composer clear-cache清掉旧的元数据缓存 - 确认 GitLab 项目已打正式 tag（
git tag v1.0.0 && git push origin v1.0.0），轻量 tag 不被 Composer 识别 - 检查项目根目录是否有
.git目录残留 —— 如果之前用path仓库方式开发过，Composer 可能误判为本地包 - 用
composer -vvv install看详细日志，重点找Executing command (CWD)和Downloading...行，确认实际请求的 URL 是否带认证头
最易被忽略的是：GitLab 实例若启用了自签名证书或反向代理重写 Host 头，auth.json 中的域名必须和实际 HTTPS 请求发出的 Host 完全一致，差一个端口或子域名都不行。
