composer识别git仓库包需在composer.json的repositories中声明type为"vcs"的源，url须为可clone地址（如https://或git@），require中包名须与仓库composer.json的name字段一致，并用dev-main等合法版本标识。
Composer 可以直接用 Git 地址作为包源，但不是简单把 git@github.com:user/repo.git 往 require 里一塞就行——它必须是符合 Composer 包规范的仓库，且需显式声明为 VCS 类型仓库。
怎么让 Composer 识别并拉取 Git 仓库里的包？
关键在 composer.json 的 repositories 字段。Composer 不会自动扫描任意 Git 仓库，必须手动注册为 vcs 类型源：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/myorg/my-private-package"
}
],
"require": {
"myorg/my-private-package": "dev-main"
}
}
注意三点：
-
url必须是可 clone 的地址（支持 HTTPS、SSH，但 SSH 需本地已配好密钥） - 包名（
myorg/my-private-package）必须与仓库中composer.json里的name字段完全一致 - 版本号不能写
latest或master，得用dev-main（Git 分支名前加dev-）、dev-develop，或带 commit hash 的dev-main#abc123
为什么 composer require 直接加 Git 地址会失败？
执行 composer require git@github.com:user/repo.git 会报错 [InvalidArgumentException] Package git@github.com:user/repo.git not found，因为 require 命令只接受 vendor/name:version 格式，不解析裸 Git URL。
正确做法分两步：
- 先确保目标仓库根目录有合法的
composer.json（含name、version或autoload等基本字段） - 在项目
composer.json中通过repositories注册该仓库，再运行composer require vendor/name:dev-branch - 如果只是临时测试，也可跳过
repositories，改用path类型仓库（见下一条）
想本地开发调试，又不想推到远程 Git 怎么办？
用 path 类型仓库，指向本地文件路径，适合边写边测：
{
"repositories": [
{
"type": "path",
"url": "../my-local-package"
}
],
"require": {
"myorg/my-local-package": "*"
}
}
要点：
-
url是相对于当前composer.json的路径，支持../和./ - 本地目录里仍需有
composer.json，且name必须匹配require中的包名 -
"*"版本会软链接（symlink）而非复制，改本地代码立刻生效，无需composer update - 上线前务必删掉
path配置，否则部署时会因路径不存在失败
配置国内镜像后，自定义 Git 仓库还走镜像吗？
不走。Composer 镜像（如阿里云、腾讯云）只代理 Packagist.org 官方索引和 ZIP 包下载，对 vcs 或 path 类型仓库完全无影响——它们始终直连原始 Git 地址。
这意味着：
- 私有 GitLab/GitHub 仓库不会被镜像加速，网络慢时 clone 耗时明显
- 若公司内网有自建 Git 服务器，建议用内网地址（如
git@git.internal:group/pkg.git），避免走公网 - SSH 方式比 HTTPS 更稳定（尤其涉及 token 过期或 2FA 时），但需确保
ssh-agent已加载对应密钥
真正容易被忽略的是：一旦在 repositories 里写了自定义源，Composer 默认会禁用 Packagist.org，除非显式加上 {"type": "composer", "url": "https://packagist.org"} 或设 "packagist.org": false 来控制回退行为。
