Composer找不到Git仓库包的根本原因是repositories配置不合法，导致其被静默忽略：type必须为"vcs"、url须为以.git结尾的可clone地址、仓库根目录需有含正确name字段的composer.json、且{"packagist.org": false}须作为独立对象置于repositories末尾。
为什么 composer require 找不到 Git 仓库里的包
不是 Git 连不上，也不是 SSH 配置错，而是 Composer 根本没去你的 Git 仓库里查——它只在你明确声明了 repositories 且配置完全合法时，才触发对 VCS 源的元数据读取。一旦漏掉 type、写错 url 格式、或 packagist.org 没关，整个配置就被静默忽略，Composer 继续默认查官方源，结果当然是 “Package not found”。
repositories 配置必须同时满足这四点
私有 Git 包的 repositories 不是“写了就行”，缺一不可：
-
type必须是"vcs"（不是"git"、"github"或空） -
url必须是可git clone的地址，且结尾只能是.git（例如https://gitlab.example.com/myorg/utils.git✅；https://gitlab.example.com/myorg/utils.git#main❌） - 该仓库根目录下必须存在合法的
composer.json（含name字段，格式为vendor/name，与你require时写的完全一致） -
{"packagist.org": false}必须作为独立对象，放在repositories数组末尾（不能嵌套、不能写成"packagist": false）
分支/Tag 名不匹配导致 404 的真实原因
报错显示 “Could not find package”，但实际是 Composer 在 Git 仓库里找不到对应版本的元数据——它会按你 require 的版本字符串，去解析远程仓库的分支名或 tag 名，然后校验是否存在。常见踩坑点：
- 你要装
dev-main，但远程仓库只有main分支，没有dev-main这个分支别名（Composer 不自动映射） - 你要装
1.2.3，但远程只有v1.2.3或release/1.2.3—— Git tag 名必须字面完全一致 - GitHub 私有库未配置
auth.json，或 URL 中带@username（如https://token@github.com/...），导致认证被跳过，元数据请求返回 404
验证 Git 包是否真被识别的最快方法
别等 composer install 报错，用这几步直接看 Composer 是否“看见”了你的仓库：
- 运行
composer config repositories，确认输出里包含你配的vcs条目，且末尾有{"packagist.org": false} - 运行
composer show vendor/name（把vendor/name换成你仓库composer.json里的name）——如果返回 “No composer.json found” 或 “Package not found”，说明仓库未生效；如果返回版本列表，说明已识别 - 临时加
--no-cache和-vvv：运行composer require vendor/name --no-cache -vvv，观察日志中是否出现Reading composer.json of vendor/name (dev-main)或类似 Git 克隆路径的日志行
Git 仓库类包的问题核心不在网络或权限，而在于 Composer 对 VCS 源的“发现机制”极其严格：它不会尝试猜测、不会 fallback、也不会合并多个源的结果。配置差一个字符，它就当那条仓库不存在。
