Composer如何配置私有GitLab仓库的访问令牌？（企业配置）

有效生成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%Composerauth.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。