type必须为"vcs"，否则仓库条目被静默忽略；url须为可git clone地址且含.git后缀；需显式添加Packagist兜底项{"type":"composer","url":"https://packagist.org","packagist":false}。
repositories里type必须写"vcs"，不是"git"或留空
写错type会导致整个仓库条目被 Composer 静默忽略，不报错、不提示、不尝试克隆——你执行composer require时它就当这行配置不存在。常见错误包括："type": "git"、"type": "package"、甚至漏掉type字段只写url。唯一合法值是"vcs"，这是 Composer 识别“这是一个可克隆的 Git/SVN/Hg 源”的开关。
验证方法很简单：删掉vendor/和composer.lock，运行composer install --no-cache -vvv，观察日志里是否出现Cloning <url></url>。没出现，大概率就是type错了。
vcs的url必须能直接被git clone消费，且带.git后缀
Composer 在解析 vcs 源时，底层调用的是git clone命令，所以url字段填的必须是终端里能直接跑通的地址。典型错误有：
-
"url": "https://github.com/myorg/sdk"→ 缺.git，git clone会失败 -
"url": "https://gitlab.example.com/myorg/sdk/-/tree/main"→ 是网页 URL，不是 Git 协议地址 -
"url": "ssh://git@git.example.com/myorg/sdk"→ 格式不标准，应写成"git@git.example.com:myorg/sdk.git"或"https://git.example.com/myorg/sdk.git"
私有仓库还需确保当前环境已配好 SSH key 或 GitHub/GitLab token，否则git clone阶段就会卡住，报错类似Permission denied (publickey)或fatal: could not read Username。
require时写dev-分支名，不是直接写分支名
想拉取main分支最新提交，得写composer require vendor/name:dev-main，而不是composer require vendor/name:main。后者会被 Composer 当作稳定版本号去 Packagist 查，必然失败。
分支名含斜杠（如feature/auth）也一样，必须写成dev-feature/auth；大小写敏感，dev-Main ≠ dev-main；远程分支不存在时，报错是Could not find branch ...，不是网络问题。
注意：dev-包默认不会随composer update自动升级，除非显式指定包名或加--with-dependencies。改了远程分支代码，本地不会自动同步，得删掉vendor/vendor/name再装。
repositories数组必须显式补上Packagist兜底项
只要你在repositories里加了一条 vcs 源，Composer 就会**自动关闭隐式 Packagist 源**——哪怕你只是想临时加一个内部 SDK，其他所有公共包（比如monolog/monolog）也会找不到。
解决办法是在repositories数组里紧跟着加一条：
{"type": "composer", "url": "https://packagist.org", "packagist": false}
关键点："packagist": false不是关掉 Packagist，而是告诉 Composer：“这个条目代表 Packagist，但请别自动启用它；我明确要它参与路由”。没有这句，这一行就无效。
顺序很重要：把私有 vcs 源放前面，Packagist 条目放后面，避免公共包误走到私有源里去查。
实际项目中，最常被忽略的是路径基准和 autoload 同步——repositories.url、autoload.ps4里的目录路径，全部以composer.json所在位置为根，不是 shell 当前路径，也不是系统 HOME。跨出项目根目录的path源会被拒绝，而 autoload 不匹配则导致Class not found，跟依赖安装成功与否完全无关。 
