Composer 接入私有 Git 仓库需配置 type 为 "vcs"，URL 使用 SSH 协议并确保认证有效，require 的包名必须与私有库 composer.json 中 name 字段完全一致，且仓库需打 Git tag 才能匹配语义化版本约束。
Composer 能接入私有 Git 仓库，但不是直接“配置仓库地址”就完事——关键在于让 composer install 能自动拉取私有库的代码，且不卡在认证环节。
私有仓库必须用 VCS 类型声明
Composer 不会把任意 Git URL 当作包源；它只识别明确标记为 vcs 的仓库。如果你只是在 repositories 里写个 "type": "git"，那不行——正确类型是 "type": "vcs"。
常见错误：把私有库当成 Packagist 镜像来配，或误用 package 类型硬编码版本，导致无法自动更新。
-
vcs类型让 Composer 主动扫描 Git 分支/Tag，支持dev-main、1.2.0等常规约束 - Git 仓库 URL 必须可被本地 shell 正常
git clone（即认证已配置好） - 不支持 HTTP Basic Auth 写在 URL 里（如
https://user:pass@github.com/...），现代 Git 客户端会拒绝这种写法
SSH 是最稳的认证方式
用 SSH 协议（git@xxx.com:org/repo.git）比 HTTPS 更可靠，避免每次交互输密码或 token，也绕过 GitHub/GitLab 的 Personal Access Token 权限陷阱。
确认 SSH 已生效：
git ls-remote git@github.com:your-org/private-package.git如果返回 ref 列表，说明密钥、Agent、
~/.ssh/config 都配对了。
- 确保
ssh-agent已启动并添加了私钥：ssh-add -l能看到对应 key - GitLab 自建实例若用非标准 SSH 端口，需在
~/.ssh/config显式声明 Host + Port - 不要在
composer.json的url字段里写成https却指望 SSH 认证生效
require 的包名必须与仓库内 composer.json 一致
Composer 查包不是靠 Git 地址，而是靠 name 字段。你 require 的 "vendor/name" 必须和私有库根目录下 composer.json 里的 "name" 完全匹配（包括大小写）。
典型翻车点：
"name": "myorg/utils"却在主项目写
"myorg/utils": "^1.0" ——看着一样，但实际仓库里是 "MyOrg/utils"，就会报 Could not find package myorg/utils。
- 私有库的
composer.json必须有name和version（或通过 tag 自动识别） - 如果用
dev-分支别名，确保分支存在且含合法composer.json - 运行
composer show --all可验证私有包是否被识别出来
避免全局配置污染，优先用项目级 repositories
别轻易改 ~/.composer/config.json 加全局 repositories，否则所有项目都会尝试连那个私有地址，CI 或队友本地容易莫名其妙失败。
正确做法是在项目根目录 composer.json 里声明：
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:your-org/private-package.git"
}
],
"require": {
"your-org/private-package": "^2.1"
}
}
- 多个私有库？追加数组项即可，无需额外插件
- 临时调试可用
composer config repositories.repo-name vcs https://...，但记得--unset清理 - 企业级场景才考虑
satis或Private Packagist，小团队纯 VCS 足够
最常被忽略的是：私有库自己没打 Git tag，却 require "^1.0" ——Composer 找不到符合语义化版本的 tag，就会静默跳过，最后报 “no matching package found”。打 tag 前先 git push --tags，不是只 git tag v1.0.0。
