私有仓库必须配置为vcs类型源，否则composer默认只查packagist.org，导致“could not find package”；需在composer.json的repositories中声明type为"vcs"、url为可git clone地址（如https://git.example.com/myorg/my-package.git），且包名须与私有库composer.json中name字段严格一致，dev分支需显式指定dev-main或打tag。
私有仓库必须配置为 Composer 的 VCS 类型源
Composer 默认只认 packagist.org，加载私有 Git 仓库前，必须显式告诉它“这是一个可用的版本控制系统源”。否则 composer require 会报 Could not find package xxx at any version 或直接跳过你的仓库。
做法是在项目根目录的 composer.json 中添加 repositories 字段，类型设为 vcs，URL 填完整 Git 地址（支持 HTTPS 或 SSH）：
{
"repositories": [
{
"type": "vcs",
"url": "https://git.example.com/myorg/my-package.git"
}
],
"require": {
"myorg/my-package": "^1.0"
}
}
注意：url 必须是可被 Composer 直接克隆的地址；如果用 SSH，确保本地 ~/.ssh/config 已配好对应 host 的密钥，且 git clone 命令能手动成功。
认证失败时优先用 SSH 而非 HTTPS 凭据
HTTPS 方式容易卡在凭据输入环节（尤其是 CI 环境），Composer 不会弹出交互式密码提示，直接报 Failed to clone https://...: Could not resolve host 或 401 Unauthorized。
更可靠的做法是改用 SSH，并确保满足以下全部条件：
- 私有仓库 URL 改成
git@git.example.com:myorg/my-package.git（注意是冒号不是斜杠） - 本地已生成并添加 SSH 密钥到 Git 服务（如 GitHub/GitLab）
-
ssh -T git@git.example.com能返回欢迎信息 - Composer 配置中禁用 HTTPS 回退：运行
composer config -g github-protocols ssh
如果必须用 HTTPS（比如企业 GitLab 启用了双因素认证），则需提前配置 Git 凭据助手或使用 Personal Access Token 替代密码，URL 写成 https://token:x-oauth-basic@git.example.com/myorg/my-package.git ——但 token 泄露风险高，不推荐长期用于生产。
包名必须与 composer.json 中的 name 字段完全一致
即使仓库克隆成功，composer require myorg/my-package 仍可能失败，常见原因是私有仓库根目录下的 composer.json 里 "name" 字段写错了。Composer 匹配依赖时严格比对这个字段，大小写、斜杠方向、拼写差一个字符都不行。
检查方法很简单：进私有仓库目录，执行 cat composer.json | grep name，确认输出类似：
"name": "myorg/my-package"
另外注意：name 不能包含大写字母（Composer 规范强制小写），也不能以 vendor/ 开头以外的路径形式出现（比如 ./my-package 或 ../myorg/my-package 都非法）。
dev-main 分支默认不可安装，必须显式指定或打 tag
如果你的私有仓库只有 main（或 master）分支、没打任何 Git tag，运行 composer require myorg/my-package 会报 Could not find a matching version of package myorg/my-package ——因为 Composer 默认只识别带语义化版本号的 tag（如 v1.0.0），不自动把分支当稳定版。
两种解法：
- 打一个正式 tag：
git tag v1.0.0 && git push origin v1.0.0，然后composer require myorg/my-package:^1.0 - 临时用分支名加
-dev后缀：composer require myorg/my-package:dev-main（注意是dev-main，不是main）
后者适合开发阶段，但上线前务必切到 tagged 版本，否则 composer install 在不同环境可能拉取到不同提交，破坏可重现性。
Git 仓库的分支策略和 tag 管理，才是决定私有包能否被稳定消费的关键。很多人卡在“能 clone 却装不上”，问题其实不在 Composer 配置，而在 Git 本身没按 Composer 的版本发现规则组织代码。
