必须在composer.json中声明vcs类型仓库，否则报“could not find package”；url需匹配协议认证（https带token或ssh配密钥），gitlab要求.git后缀，分支须用dev-前缀加#指定，包名与私有库composer.json的name字段须完全一致。
直接用 composer require 拉私有 Git 仓库的代码，90% 的失败不是因为命令写错，而是 repositories 缺失、协议不匹配或分支命名不符合 Composer 的版本解析规则。
必须在 composer.json 中声明 vcs 类型仓库
Composer 默认只认 Packagist，不会自动扫描任意 Git 地址。哪怕你把仓库地址写进 require，没配 repositories 就会报 Could not find package vendor/name at any version。
-
"type": "vcs"是唯一有效的类型，写"git"或"package"都会被忽略 - URL 必须可被本地
git clone直接执行：HTTPS 地址需带认证（如https://oauth2:TOKEN@gitlab.example.com/group/repo.git），SSH 地址需确保ssh -T git@gitlab.example.com成功 - GitLab 私有实例要求 URL 末尾带
.git后缀（15+ 版本强制），GitHub 则建议省略 - 多个私有源要按优先级排序，私有仓库配置必须放在
packagist.org条目之前，否则会被跳过
拉取指定分支必须用 dev- 前缀 + # 分支名
分支名不能直接写 main 或 feature/login，否则 Composer 解析失败或装错 commit。
- 正确格式是
vendor/name:dev-main#main或vendor/name:dev-feature%2Flogin#feature/login（含斜杠时必须 URL 编码） -
dev-是 Composer 识别开发分支的硬性前缀，#main后缀才是实际 Git 分支名，两者缺一不可 - 如果只写
dev-main不加#main，Composer 可能缓存旧 commit，导致拉不到最新代码 - 首次拉取非默认分支（如
dev-feature/auth）时会较慢，因为 Composer 要扫描所有远程分支来匹配dev-前缀
认证方式选 SSH 还是 HTTPS？看运行环境
CI/CD 环境推荐 SSH，开发机推荐 HTTPS + Token，二者不能混用，且配置位置完全不同。
- SSH 方式：依赖系统级
ssh-agent和~/.ssh/config，composer.json中 URL 必须是git@gitlab.example.com:group/repo.git格式；密钥权限必须是600，且IdentityFile要写绝对路径 - HTTPS + Token 方式：Token 写在 URL 里（如
https://oauth2:abc123@gitlab.example.com/group/repo.git）或通过composer config gitlab-oauth.gitlab.example.com abc123全局配置；注意 GitLab 要求勾选read_repository权限 - 别指望
github-oauth配置能解决 GitLab 或自建 Gitea 的 SSH 认证问题——那是纯 HTTPS 场景专用 - Windows 用户要注意 Git Bash 和 PowerShell 的 OpenSSH 不互通，
ssh-add加的密钥可能只对其中一个生效
拉下来却 autoload 失败？检查私有包自身的 composer.json
即使拉取成功，类找不到往往不是项目配置问题，而是私有包没写对 autoload 或 name 字段。
- 私有仓库根目录的
composer.json必须有"name": "vendor/package"，且和项目require中的包名完全一致（包括大小写） -
autoload必须覆盖实际代码路径，例如"psr-4": {"Vendor\Package\": "src/"}，但代码实际在lib/下就无法加载 - 如果私有包本身依赖其他私有包，所有上游仓库都得列在当前项目的
repositories里，漏一个就会卡在Resolving dependencies - 运行
composer show vendor/package可确认是否识别到该包及其版本约束，这是验证配置是否生效的最快方式
最常被忽略的是：私有仓库的 composer.json 文件必须存在且合法，否则 Composer 在解析阶段就直接跳过整个分支，连认证环节都不会触发。
