如何通过Composer管理私有GitLab包？Token配置与认证全流程-composer-PHP中文网

composer必须显式声明vcs类型仓库，repositories须为顶层字段且每条含"type":"vcs"，url须带.git后缀，auth.json需严格匹配域名与权限，require包名须与私有库composer.json中name字段逐字符一致。

如何通过composer管理私有gitlab包？token配置与认证全流程

Composer 不会自动发现或扫描 GitLab 私有项目，只认你明确定义的 repositories 源。漏掉这一步，composer install 会静默跳过私有包，甚至报 Could not find package。

关键点：

repositories 必须是 composer.json 的顶层字段，不能嵌套在 config、scripts 或其他任意位置
每条仓库配置必须含 "type": "vcs" —— 写成 "package"、"path" 或直接省略，Composer 都当它不存在
url 必须是可直接 git clone 的 HTTPS 地址，结尾带 .git，例如："https://gitlab.example.com/group/my-pkg.git"
如果 GitLab 启用了子路径（如 /gitlab），URL 中也得带上，否则 API 请求失败
SSH 地址（如 git@gitlab.example.com:group/pkg.git）不走 Token 认证流程，本地开发可用，但 CI 环境通常禁用 SSH，推荐统一用 HTTPS

填错任意一项，composer install 就会卡在 401 或反复弹密码框——不是没配，而是配了 Composer 也根本没读。

常见错误现象：

正确做法：

Linux/macOS：文件路径必须是 ~/.composer/auth.json（不是 ~/.config/composer/auth.json），权限设为 600：chmod 600 ~/.composer/auth.json
Windows：路径是 %APPDATA%\Composer\auth.json
字段名必须是 http-basic（不是 gitlab-token、token 或 access_token）
域名 key 必须和 repositories.url 的 host 完全一致：比如 URL 是 https://gitlab.example.com:8443/group/pkg.git，key 就得是 "gitlab.example.com:8443"，多一个斜杠、少一个端口都不行

内容示例：

{ "http-basic": { "gitlab.example.com": { "username": "oauth2", "password": "glpat-xxxxxxxxxxxxxxxxxxxx" } } }

Composer 拉取私有包分两步：先调 GitLab API 获取元数据（/api/v4/projects/...），再走 git clone 下代码。少一个权限，就在不同阶段失败。

Github Auto

管PR、盯Issue、跑CI、发Release——GitHub仓库日常运维扔给它。少开几个Chrome标签页。

下载

Token 必须满足：

别用个人账号长期 Token，建议为 Composer 单独建最小权限 Token，定期轮换。

Composer 不按 Git 路径匹配，只严格比对 name 字段。差一个字母、大小写、斜杠方向，都会失败，且错误信息极其模糊（常显示 Package not found）。

验证方式：

打开私有包根目录下的 composer.json，确认 "name": "acme/utils"
主项目的 require 必须写成 "acme/utils": "dev-main"，不能是 "Acme/utils"、"acme-utils"、"acme/utils-dev"，也不能省略 vendor 段
如果私有库 name 是 "acme/my-package"，但你在 require 里写 "acme/my_package"，照样失败

最易被忽略的是大小写和 vendor 名拼写——GitLab 项目路径和 Composer 包名是两个独立系统，必须人工对齐。