composer识别私有依赖需正确配置repositories为顶层字段，支持vcs（git仓库）、composer（私有源）、path（本地包）三类；vcs须用.git结尾url，composer源url末尾需加/，path仅接受相对路径，凭证通过auth.json按优先级存放。
要在PHP项目中让Composer识别并安装私有Git仓库、本地包或企业级私有源中的依赖，必须正确配置repositories参数——写错位置、类型或URL格式，Composer会静默跳过，不报错也不提示。
基础结构：repositories必须放在composer.json最外层
打开项目根目录下的composer.json，确认repositories是与require、autoload同级的顶层字段，不是嵌套在config、scripts或extra里。
错误示例："config": { "repositories": [...] } → Composer完全忽略。
正确结构必须是：
{ "repositories": [ ... ], "require": { ... }, "autoload": { ... }}
【repositories数组必须是JSON根对象的直接子键】，否则整个配置失效。
vcs类型：直连GitLab/GitHub/Bitbucket私有仓库
适用于临时拉取尚未发布到Packagist的分支、Tag或提交，无需搭建镜像服务。
方法一：SSH方式（推荐，CI/CD稳定）
第一步：确认本地已配置SSH密钥且能免密访问目标Git服务器，执行ssh -T git@gitlab.example.com应返回欢迎信息。
第二步：在repositories中添加：
{ "type": "vcs", "url": "git@gitlab.example.com:acme/utils.git" }
注意：URL末尾必须带.git，缺了就无法克隆，Composer也不会报错，只会跳过该仓库。
方法二：HTTPS + auth.json认证（适合无SSH权限场景）
先创建auth.json文件（位置见后文），再填入：
{ "type": "vcs", "url": "https://gitlab.example.com/acme/utils.git" }
⚠️ 不要写成https://gitlab.example.com/acme/utils（缺.git）或https://gitlab.example.com/acme/utils/-/tree/main（是网页地址，非Git协议地址）。
composer类型：对接Satis/Artifactory/Private Packagist等私有源
这类服务提供完整的packages.json索引，支持全局搜索和版本约束解析，适合企业级长期使用。
第一步：确保私有源URL可被直接访问，执行curl -I https://my-private-repo.example.com/packages.json返回HTTP 200。
第二步：在repositories中声明：
{ "type": "composer", "url": "https://my-private-repo.example.com/" }
第三步：必须补上Packagist兜底项（否则连monolog都装不上）：
{ "type": "composer", "url": "https://packagist.org", "packagist": false }
⚠️ 【URL末尾的斜杠/不能省】，少一个会导致Composer请求https://x.y.z/packages.json变成https://x.y.zpackages.json而404。
第四步：把私有源放数组首位，确保优先命中：
"repositories": [ { "type": "composer", "url": "https://my-private-repo.example.com/" }, { "type": "composer", "url": "https://packagist.org", "packagist": false }]
path类型：加载本地开发中的扩展包
适用于边写边测的本地包，比如./packages/my-utils，避免反复composer publish。
方法一：简单声明
在repositories中加入：
{ "type": "path", "url": "./packages/my-utils" }
这一步操作起来很简单，直接把路径填对就行。
方法二：强制锁定版本（防止dev-main被稳定性策略过滤）
确保./packages/my-utils/composer.json中有"version": "1.0.0"，且项目级composer.json中require写为"mycompany/utils": "1.0.0"。
注意：url必须是相对路径，不能用file://或绝对路径，否则在Docker或CI中必然失败。
auth.json：凭证存放位置与格式规范
90%的401/403错误源于auth.json没放对地方或字段名写错。
正确路径（按优先级从高到低）：
① 项目根目录：./auth.json（仅作用于当前项目）
② 用户家目录：~/.composer/auth.json（全局生效，但会被项目级覆盖）
③ 环境变量：COMPOSER_AUTH（内容为JSON字符串，适合CI）
文件内容必须是标准JSON，例如GitLab HTTPS认证：
{ "http-basic": { "gitlab.example.com": { "username": "oauth2", "password": "glpat-xxxxxxxxxxxxxxxxxxxx" } }}
⚠️ 【域名key必须与vcs URL中的主机名完全一致】，比如URL是https://gitlab.example.com/acme/pkg.git，key就必须是"gitlab.example.com"，不能写成"https://gitlab.example.com"或"gitlab"。
