必须用vcs类型显式声明仓库，URL须以.git结尾且可git clone，repositories中私有源放前、packagist.org兜底放后，认证通过auth.json或OAuth token配置，require中的包名必须与私有库composer.json的name字段完全一致。
要在Composer项目中正确引入GitLab、GitHub或Bitbucket上的私有代码库，必须用vcs类型显式声明仓库，否则Composer会完全跳过该地址、不报错也不提示——这是90%的“require不生效”问题根源。
第一步：确认vcs仓库URL是否合法可克隆
打开终端，执行：git ls-remote -h https://gitlab.example.com/myorg/sdk.git。能列出分支说明URL有效；若报401/403，说明认证未就绪；若报“fatal: unable to access”，大概率是URL缺.git后缀或写成了网页地址。
【URL必须以.git结尾，且能被git clone直接消费】
常见非法写法：https://github.com/myorg/sdk（缺.git）、https://gitlab.com/myorg/sdk/-/tree/main（HTML页面）、git@gitlab.com:myorg/sdk（SSH未配密钥时会卡住）。
第二步：在composer.json中正确声明vcs仓库
进入项目根目录，编辑composer.json，在repositories数组开头插入一项：
{ "type": "vcs", "url": "https://gitlab.example.com/myorg/sdk.git" }
注意：type必须小写vcs，不能写成git、package或留空；url必须与git ls-remote测试时完全一致；多个vcs仓库按优先级从高到低排列，Composer只取第一个匹配name的仓库。
这一步操作起来很简单，直接把上面那行JSON粘贴进数组就行。但别忘了：一旦你加了任何repositories，Packagist官方源就会被自动关闭——后面还得补上它。
第三步：显式恢复packagist.org作为兜底源
在同一个repositories数组里，把Packagist官方源加在vcs项之后：
{ "type": "composer", "url": "https://packagist.org", "packagist": false }
这个配置不是“启用”Packagist，而是“显式禁用隐式行为”。没有它，连monolog/monolog这种通用包都会报Could not find package。
顺序很重要：私有vcs放前面，Packagist兜底放后面。如果反过来，Composer会先查Packagist，发现没有你的私有包，就直接报错退出，根本不会去看后面的vcs项。
第四步：为私有仓库配置认证凭证
方法一（推荐，HTTPS + auth.json）：
在项目根目录创建auth.json文件，内容为：
{ "http-basic": { "gitlab.example.com": { "username": "_", "password": "glpat-xxx..." } } }
GitLab token需有read_repository权限，GitHub用repo权限，Bitbucket必须用App Password（账号密码已停用）。
方法二（全局OAuth，仅限GitHub/GitLab）：
运行composer config -g github-oauth.github.com xxx或composer config -g gitlab-oauth.gitlab.com yyy。注意：该配置会被项目级auth.json完全覆盖，二者不要混用。
【auth.json必须放在项目根目录，且不能提交到Git】
第五步：在require中写对包名和版本
第一步：确认私有仓库composer.json里"name"字段值，例如"myorg/sdk"。
第二步：在项目composer.json的require中写：
"myorg/sdk": "dev-main" → 拉取main分支最新代码
"myorg/sdk": "dev-feature/auth#abc1234" → 拉取feature/auth分支中指定commit
"myorg/sdk": "v1.2.3" → 要求该仓库tag存在且composer.json中"version"匹配（不推荐，vcs优先走分支/commit）
关键点：Composer不会扫描整个Git仓库找包，它只在require中出现的vendor/name与vcs仓库的name字段**完全一致**时，才去那个URL解析。写错一个字母，就静默失败。
第六步：清除缓存并执行安装
运行composer clear-cache，再执行composer require myorg/sdk:dev-main --no-update，最后composer update myorg/sdk。
不要直接composer install——它只读composer.lock，而lock里还没有你的私有包记录。
如果报Failed to clone https://...，回到第一步检查git ls-remote；如果报Could not find package，重点核对require中的name是否与私有库composer.json中name一字不差。
