Composer必须显式声明vcs类型仓库，repositories须为顶层字段且每条含"type":"vcs"，url须带.git后缀，auth.json需严格匹配域名与权限，require包名须与私有库composer.json中name字段逐字符一致。
composer.json 必须显式声明 vcs 类型仓库
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
auth.json 路径、字段名与域名必须三者严丝合缝
填错任意一项，composer install 就会卡在 401 或反复弹密码框——不是没配，而是配了 Composer 也根本没读。
常见错误现象：
- 运行
composer update -v日志里没有Authorization: Bearer glpat-请求头 -
composer config --global --list | grep gitlab查不到对应配置 - 提示
Authentication required却没报具体域名错误
正确做法：
- 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" } } }
Personal Access Token 权限缺一不可
Composer 拉取私有包分两步：先调 GitLab API 获取元数据（/api/v4/projects/...），再走 git clone 下代码。少一个权限，就在不同阶段失败。
Token 必须满足：
- 类型只能是 Personal Access Token（不是 Deploy Token、CI_JOB_TOKEN 或 OAuth App Token）
- 勾选
read_api：否则报403 Forbidden on /api/v4/projects/ - 勾选
read_repository：否则报Failed to execute git clone --mirror - 企业 GitLab 实例上，该用户还需对目标项目有 Reporter 及以上权限（Guest 不行）
- 生成后立即复制保存——页面刷新后无法再次查看明文
别用个人账号长期 Token，建议为 Composer 单独建最小权限 Token，定期轮换。
require 的包名必须和私有库 composer.json 的 name 字段逐字符一致
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 包名是两个独立系统，必须人工对齐。
