私有 Git 仓库必须在 composer.json 的 repositories 中显式声明为 "vcs" 类型，URL 不带 .git 后缀且需含认证（如 PAT），并确保 tag/分支命名符合 Composer 版本规则（如 v1.2.3 或 dev-main）。
私有 Git 仓库必须用 composer.json 的 repositories 显式声明
Composer 默认只认 Packagist，不自动发现或信任任意 Git 地址。哪怕你把代码放 GitHub 私有库、GitLab 内网库、甚至本地 file:// 路径，都得在项目根目录的 composer.json 里手动加一条 repositories 配置，否则 composer install 根本看不到它。
常见错误是只改了 require，漏掉 repositories，结果报错：Could not find package vendor/name at any version。
-
类型必须写对：Git 仓库填
"type": "vcs"，别写成"git"或"package" -
URL 要能被机器直接 clone：HTTPS 地址需带认证（见下条），SSH 地址要确保当前用户已配好
~/.ssh/id_rsa且 Agent 已启动 -
不要加
.git后缀（虽然部分情况能 fallback，但 Composer 官方文档明确建议省略）
示例（GitHub 私有库）：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/your-org/your-private-package"
}
],
"require": {
"your-org/your-private-package": "^1.0"
}
}
HTTPS 私有库拉取失败？先解决认证问题
Composer 用 git clone 拉代码，HTTPS 方式默认走系统 git 凭据管理器。如果没提前配置凭据，composer install 会卡住或报错：Failed to clone https://... fatal: could not read Username for 'https://github.com': No such device or address。
最稳的方式不是输密码（不支持交互式输入），而是用 Personal Access Token（PAT）或 Git 凭据缓存。
- GitHub/GitLab：生成 PAT，拼进 URL，如
"url": "https://<token>@github.com/your-org/pkg"（注意 token 权限要含repo） - 公司内网 GitLab：用
git config --global credential.helper store，然后手动跑一次git clone https://user:pass@gitlab.internal/pkg存凭据 - 别用
http-basic配置全局 auth —— 它只对 Packagist 生效，对自定义vcs仓库无效
composer require 不自动加 repositories，得自己补
很多人以为 composer require your-org/your-private-package 会像拉 Packagist 包一样自动搞定一切。实际上，它只会往 require 里写一行，repositories 一栏完全不动。结果就是下次 composer install 在 CI 或新机器上直接失败。
- 正确流程：先手动编辑
composer.json加好repositories，再运行composer require - 如果已经
require了但没配repositories，composer update会报错，此时必须补上再重试 - CI 环境尤其要注意：不能依赖本地凭据缓存，得用 token 拼 URL 或挂 SSH key
Tag 和分支名必须符合 Composer 版本约束规则
Composer 解析 Git 仓库版本，靠的是 tag 名（如 v1.2.3、1.2.3）或分支名（如 dev-main、dev-develop）。如果你的私有库打了个 release-2024 的 tag，又在 require 写 "^2.0"，Composer 找不到匹配版本，会退回到 dev-master 或直接报错。
- Tag 命名优先用语义化版本，前面可加
v（v1.0.0）或不加（1.0.0），两者都能识别 - 分支名必须带
dev-前缀才能当开发版用，比如dev-feature/login对应"dev-feature/login as 1.0.x-dev" - 别指望
main或master分支自动变成dev-main—— 必须显式写"dev-main"或设"default-branch": "main"（Composer 2.2+ 支持）
这事容易拖到上线前才发现，因为本地开发时可能一直用 dev-master 硬顶，一换版本约束就崩。
