Composer需在composer.json中声明vcs仓库，用dev-前缀引用分支，tag需与version字段一致，私有库须配SSH认证，--prefer-source保留.git目录，且仓库composer.json必须有合法name字段。
composer怎么从Git仓库直接装包
能，但不是直接写 git clone 地址进去就完事。Composer 会把 VCS 仓库当作「伪包源」处理，必须显式声明为 repository 类型，否则它根本不会去拉 Git 分支或 tag。
常见错误现象：Could not find package xxx at version yyy，其实仓库地址完全正确，只是没告诉 Composer “这地方是个代码仓库，不是 Packagist”。
- 必须在
composer.json根对象里加"repositories"字段，类型设为"vcs" - 地址必须是可被
git clone的完整 URL（支持 HTTPS、SSH，不支持 GitHub Web 页面链接） - 如果目标分支不是
main或master，得用dev-前缀引用，比如"dev-feat/login" - 别把私有仓库的 SSH 地址写成
git@github.com:user/repo.git就完事——Composer 默认不走 SSH agent，容易卡在权限拒绝
private Git 仓库怎么配 SSH + 认证
Composer 走 SSH 拉代码时，默认不复用你终端里的 ssh-agent，除非你显式配置 git 的 core.sshCommand 或让 Composer 用系统 git。
使用场景：公司内网 GitLab、自建 Gitea、或者 GitHub 私有 repo。
- 先确保本地
git clone git@xxx能通（验证 ssh-agent 和 key 是否加载） - 运行
git config --global core.sshCommand "ssh -o IdentitiesOnly=yes"，避免多 key 冲突 - 在
composer.json的repositories里写 SSH 地址，例如："url": "git@gitlab.example.com:group/pkg.git" - 如果仍失败，临时加
"options": {"ssl": {"verify_peer": false}}（仅调试，勿提交）
dev-main 和 v1.2.3 版本号怎么对应 Git 分支/Tag
Composer 不解析 Git 的 branch 名字本身，而是靠 composer.json 文件里写的 "version" 字段——但这个字段只在 tag 上生效，分支上会被忽略。
也就是说：tag 对应稳定版（v1.2.3），分支对应开发版（dev-main），两者不能混用逻辑。
- 打 tag 时，
composer.json里的"version"必须和 tag 名一致，比如 tagv2.0.0→"version": "2.0.0" - 分支名任意，但 require 时必须写
dev-branch-name，例如"dev-fix/http-timeout" - 如果分支里改了
composer.json的"version"，Composer 不认——它只看 tag 元数据 - 别在
require里写"dev-main as 1.0.0"来“伪装”版本，下游依赖解析会出错
为什么 install 后 vendor 里没看到 .git 目录
因为 Composer 默认用 dist 方式安装：下载 zip 包解压，不保留 Git 历史。这不是 bug，是设计选择——减小体积、加速安装、避免污染。
但如果你需要本地改代码、提 PR、或者跑 git log 查变更，就得强制走 source 模式。
- 全局启用：
composer config --global prefer-source true - 单次启用：
composer install --prefer-source或composer update --prefer-source - 注意：私有仓库若没开 archive 下载（如自建 Gitea 关了 zip download），
--prefer-dist会直接失败 - CI 环境建议保持
--prefer-dist，除非真要 patch 依赖
最常被忽略的是：VCS 仓库的 composer.json 必须有合法的 "name"（格式 vendor/name），否则即使地址对、分支存在，Composer 也会静默跳过——连报错都没有。
