必须在composer.json顶层repositories中正确配置私有gitlab仓库，使用type:"vcs"和以.git结尾的url，并确保require中的包名与私有库composer.json的name字段完全一致；同时需通过auth.json或composer config配置匹配域名的http basic认证凭据，最后验证源加载、认证触发、包结构合规并清除缓存重试。
要在PHP项目中成功安装企业内部GitLab私有包，必须让Composer明确知道去哪里找、用什么凭证认证、按什么规则加载——少一个环节，composer install就会卡在“Could not find package”或“401 Unauthorized”。
在composer.json中声明私有仓库源
这一步决定Composer是否“看见”你的私有库。repositories必须写在项目级composer.json最外层，不能嵌套进config、extra或scripts里。
打开项目根目录下的composer.json，在顶层添加repositories字段：
```json
{"repositories": [{"type": "vcs", "url": "https://gitlab.example.com/acme/utils.git"}]}
```
【url必须以.git结尾】，写成https://gitlab.example.com/acme/utils会导致Composer静默跳过该源；【type必须显式写为"vcs"】，写成"git"、"package"或留空，Composer一律忽略。
然后在require段写明包名和版本：
```json
{"require": {"acme/utils": "dev-main"}}
```
注意：包名必须与私有库自身composer.json中的"name"字段逐字符一致——大小写、斜杠、vendor段都不能错。若私有库写的是"Acme/Utils"，这里写"acme/utils"就找不到。
配置GitLab身份认证凭据
认证失败90%不是Token无效，而是auth.json放错位置、权限不对或域名不匹配。
方法一：使用全局auth.json（推荐开发环境）
在Linux/macOS上创建~/.composer/auth.json，内容严格如下：
```json
{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}}
```
执行chmod 600 ~/.composer/auth.json，否则Composer直接跳过读取。
方法二：使用项目级auth.json（推荐CI/CD或敏感项目）
在项目根目录下新建auth.json，结构同上，但域名key必须与repositories.url的host完全一致——如果URL是https://gitlab.internal:8080/org/pkg.git，key就得是"gitlab.internal:8080"，端口不能省。
方法三：用命令行注入（适合临时调试）
运行：composer config --global http-basic.gitlab.example.com oauth2 glpat-xxx
这条命令会把凭据写入~/.composer/config.json，比手动编辑更安全，避免JSON格式错误。
验证私有包是否可被正确解析
第一步：确认Composer已加载你的仓库源
运行composer show -p | grep acme/utils，如果有输出，说明源已识别；若无输出，说明repositories配置未生效。
第二步：检查认证是否触发
加-v参数运行composer install -v，观察日志中是否出现类似GET https://gitlab.example.com/api/v4/projects/...的请求行。没有该行，说明凭据根本没被读取或域名不匹配。
第三步：确认私有包自身结构合规
登录GitLab，打开私有仓库根目录，检查是否存在composer.json文件，且必须包含"name"和"autoload"字段。缺少autoload会导致类能下载却无法new调用。
第四步：强制刷新缓存并重试
执行composer clear-cache → rm -rf vendor composer.lock → composer install。缓存残留常导致旧错误持续复现。
