有效生成GitLab personal access token需勾选read_repository权限，配置composer.json为vcs类型HTTPS地址，auth.json须置于全局目录且host与URL完全一致，并清除缓存验证。
GitLab personal access token 怎么生成才有效
Composer 拉取私有 GitLab 仓库时，必须用 personal access token（不是 deploy token、不是 CI token），且权限至少勾选 read_repository。GitLab UI 里如果只勾了 api 或 read_user，composer install 会报 401 Unauthorized，但错误信息里往往只显示 “Could not fetch”，不提权限问题。
- 路径：GitLab 用户头像 → Settings → Access Tokens → 填名称、过期时间、勾选
read_repository - 生成后立刻复制保存——页面刷新就再也看不到明文 token
- 企业 GitLab 实例（如
gitlab.example.com）需确认该 token 所属用户有对应项目的 Reporter 及以上权限，Guest不行
composer.json 里怎么写 repository 配置
不能只靠 auth.json 就完事；私有 GitLab 仓库必须显式声明为 vcs 类型，并指定完整 HTTPS 地址。如果写成 git@ SSH 地址，Composer 会跳过 token 认证直接走 SSH 密钥，而企业内网往往禁用 SSH 克隆。
-
type必须是vcs，不是package或path -
url必须是 HTTPS 格式，且包含域名和完整路径，例如：https://gitlab.example.com/group/project-name.git - 不要在 URL 里硬编码 token（如
https://token:x-oauth-basic@gitlab.example.com/...），既不安全又容易被日志泄露
示例片段：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/mygroup/mylib.git"
}
]
}
auth.json 怎么配才不被忽略
Composer 只读取项目根目录或 COMPOSER_HOME 下的 auth.json。如果放错位置（比如放在子目录、或写成 auth.json.dist），token 完全不会生效，composer install 仍会卡在认证环节。
- 推荐放在全局配置目录：
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows） - 内容格式必须严格，host 名要和
composer.json中url的域名完全一致（注意端口、协议、子路径） - GitLab 实例启用了自定义端口（如
:8443）或子路径（如/gitlab），host 字段就得写成"gitlab.example.com:8443"或"gitlab.example.com/gitlab"
正确 auth.json 示例：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-abc123xyz..."
}
}
}
为什么 composer update 有时还是走匿名请求
Composer 默认启用 cache，如果之前失败过（比如 token 过期或输错），它可能缓存了 401 响应，后续即使改对了配置，依然返回旧错误。更隐蔽的是：GitLab 返回的 WWW-Authenticate header 如果含空格或非常规值，某些 Composer 版本（特别是 2.2.x）会解析失败，静默降级为匿名请求。
- 先清缓存：
composer clear-cache - 加
-vvv参数重试，观察输出中是否出现Reading composer.json of mygroup/mylib和Downloading https://gitlab.example.com/api/v4/projects/...请求行 - 若看到
Failed to decode response: Syntax error，大概率是 GitLab 版本与 Composer HTTP client 兼容性问题，可临时降级到composer self-update 2.1.14验证
真正起作用的永远是三者同时对齐：token 权限正确、composer.json 中 url 域名与 auth.json host 完全一致、且没有被本地代理或企业防火墙劫持 HTTP header。
