Composer安装Git分支需用dev-分支名格式并配置VCS仓库；若失败，检查minimum-stability、缓存、分支名拼写、composer.json位置及GitLab认证；验证时应检查.git目录和git log。
composer require 时指定 Git 分支的语法
Composer 默认安装 dist 包（即 Packagist 上发布的稳定版本），但要装 GitHub/GitLab 上某个开发中的分支（比如 dev-feature/auth 或 main），必须显式告诉 Composer：这是个 VCS 仓库，且目标是某分支而非 tag。
关键不是加 @dev 后缀那么简单——那是旧写法，现在更可靠的方式是用 vcs 类型 + branch-alias 或直接在 require 中写明分支名。
-
composer require vendor/name:dev-main—— 安装main分支（注意dev-前缀是必需的） -
composer require vendor/name:dev-develop—— 安装develop分支 - 如果包名在 Packagist 上不存在（比如私有库或刚 fork 的项目），需先在
composer.json的repositories中声明源：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/package-name"
}
],
"require": {
"yourname/package-name": "dev-main"
}
}
然后运行 composer update yourname/package-name。不加 repositories 就会报错：Could not find package yourname/package-name。
为什么 dev-xxx 不生效？常见原因和修复
写了 dev-main 却还是装了旧版，大概率是以下三类问题之一：
- 目标仓库的
composer.json没有正确设置"minimum-stability": "dev"，或没设"prefer-stable": false—— Composer 默认跳过dev-版本，除非明确允许 - 本地已缓存旧版本的 dist 包，
composer clear-cache再重试 - 分支名拼错，比如把
feat/login写成feature/login；Git 分支名区分大小写，Main≠main - GitHub 仓库未启用
composer.json的自动解析（比如缺少composer.json，或文件放在子目录里）—— Composer 要求该文件必须在仓库根目录
GitLab 私有仓库需要额外配置认证
GitLab 自托管实例或私有项目，Composer 默认无法拉取，必须配 token 或 SSH。
- 推荐用
auth.json（位于COMPOSER_HOME目录下，默认是~/.composer/auth.json）：
{
"gitlab-token": {
"gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
其中 glpat-... 是你在 GitLab 的 Personal Access Token，权限至少含 read_repository。
- 如果用 SSH 地址（如
git@gitlab.example.com:group/project.git），确保本地ssh-agent已加载对应密钥，且~/.ssh/config正确配置了 Host 别名 - 别用 HTTPS 地址 + 密码——Composer 不支持交互式密码输入，会卡住
安装后如何验证是否真用了目标分支
别只信 composer show 输出的版本号，它可能显示 dev-main 但实际代码仍是旧 commit。
- 进
vendor/yourname/package-name/目录，执行git log -1，确认 HEAD 是你期望的分支最新提交 - 检查
vendor/yourname/package-name/.git/是否存在 —— 如果没有，说明 Composer 下载的是 dist 包（zip），不是 git clone，那分支指定就失效了 - 强制走源码模式：在
composer.json加"preferred-install": {"yourname/package-name": "source"}，或全局设composer config --global preferred-install source
分支安装不是“点一下就完事”，它绕过了 Packagist 的版本校验，容易因依赖冲突、autoload 错误或分支不稳定导致运行时报错——上线前务必在 CI 中跑完整测试，别只看 composer install 成功了就认为没问题。
