GitLab私有包require不生效主因是repositories未置顶层或缺"type": "vcs"，且require包名须与私有库composer.json中name字段严格一致，认证应通过auth.json（https）或deploy key（ssh）配置。
GitLab私有包为什么require不生效
不是网络不通，也不是权限没开，而是Composer根本没去查你那个仓库——repositories没声明，或者声明位置错了。它只认顶层repositories数组里的条目，嵌套在config、scripts甚至extra里都无效。
-
repositories必须是composer.json的直接子字段，不能缩进、不能包裹在其他对象里 - 每条仓库配置必须含
"type": "vcs"，写成"package"或漏掉type，Composer就当它不存在 - URL必须带
.git后缀，比如"https://gitlab.example.com/group/pkg.git"，裸地址/group/pkg会被拒绝 - 私有包的
name字段（在它自己composer.json里）必须和你require时写的完全一致，包括大小写、斜杠方向，myorg/utils≠MyOrg/utils
auth.json里填http-basic还是gitlab-token
取决于GitLab版本和部署方式。2026年主流自建GitLab（15+）和gitlab.com都支持两种，但行为不同：
Conventional Git
下载
Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。
- 用
http-basic：用户名固定填"oauth2"，密码填完整glpat-xxx令牌，兼容性最好，CI里也容易用COMPOSER_AUTH环境变量注入 - 用
gitlab-token：直接映射域名到令牌字符串，语义更清晰，但部分旧版Composer（ - 文件路径必须是项目根目录下的
auth.json或~/.composer/auth.json（Windows是%APPDATA%\Composer\auth.json），权限设为600 - 域名key必须和URL host完全一致：
"gitlab.example.com"不能写成"https://gitlab.example.com"或"www.gitlab.example.com"
OAuth2令牌权限和生成细节
令牌不是生成了就能用，缺权限会在不同阶段失败：
- 必须勾选
read_api和read_repository两项，缺一不可——前者用于获取项目元数据，后者用于实际克隆代码 - 别用Deploy Token，它不支持API调用，
/api/v4/projects/xxx请求会直接403 - 生成后页面只显示一次明文，刷新即消失，务必立刻复制保存
- 如果GitLab启用了双因素认证（2FA），HTTPS方式必须用PAT，不能用账号密码
- 令牌过期、被管理员回收、或权限被修改，都会导致后续
composer install报401 Unauthorized或403 Forbidden
HTTPS URL里能不能直接拼token
不能。像"https://glpat-xxx@gitlab.example.com/group/pkg.git"这种写法已被弃用，且存在安全风险（token可能泄露到日志、CI缓存、代理记录中）。
- Composer官方明确不推荐硬编码token到URL，也不再保证兼容性
- 正确做法是把token放进
auth.json，让Composer自动注入Authorization: Bearer头 - 如果URL里误写了token，
composer install -vvv日志里仍看不到Authorization头，说明它根本没读你的凭证 - SSH方式可绕过token，但要求
ssh-agent已加载对应私钥，CI环境通常禁用，不建议作为主力方案
composer config --list是否输出对应域名，运行composer install -vvv看请求头里有没有Authorization，比反复改composer.json有效得多。 
