composer 从 git 分支安装需显式声明 vcs 仓库并使用 "dev-分支名" 格式版本约束，且要求分支真实存在、未被依赖锁定、vendor 和 lock 文件已清理；否则仍会回退到 packagist 版本或 master 分支。
Composer 默认拉取的是 composer.json 中声明的包版本（如 "^2.0"），但如果你想直接从某个 Git 分支安装（比如开发中的 dev-feature/login），必须绕过 Packagist 的版本映射，用「仓库重写 + 版本约束」组合实现——不是简单改个版本号就能生效。
为什么 "dev-main" 或 "dev-develop" 有时不生效
Composer 会把形如 "dev-main" 这样的字符串当作「稳定性标识符」处理，但它只在满足两个前提时才真正拉取对应分支：
- 该分支名在远程 Git 仓库中真实存在（大小写敏感，
main≠master） - 包未在 Packagist 上注册，或你已在
repositories中显式声明了该 Git 仓库（否则 Composer 仍优先查 Packagist 的 metadata） - 版本约束未被其他依赖项锁定（例如父项目已锁死
vendor/foo/bar到1.2.3，那"dev-main"就会被忽略）
正确配置 Git 仓库并指定分支的三步法
以拉取 GitHub 仓库 git@github.com:acme/package.git 的 dev-auth-refactor 分支为例：
- 在项目根目录的
composer.json中添加自定义仓库：
"repositories": [
{
"type": "vcs",
"url": "git@github.com:acme/package.git"
}
]
- 将依赖项版本设为
"dev-dev-auth-refactor"（注意前缀dev-和分支名完全一致） - 运行
composer update acme/package --with-dependencies（加--with-dependencies避免因锁文件缓存导致分支未更新）
dev- 前缀和 #commit-hash 的区别与风险
"dev-main" 每次 composer install 都会拉取该分支最新 commit；而 "dev-main#abc1234" 会固定到某次提交，但有隐性陷阱：
-
#abc1234不是语义化版本，Composer 不校验其签名或 GPG 状态，仅做 shallow clone - 如果该 commit 被 force-push 覆盖，本地 lock 文件记录的 hash 就失效，下次 install 会报
Could not find package ... at commit abc1234 -
dev-分支名方式更安全，适合持续集成场景；#hash仅建议用于临时调试或灰度验证
常见错误：拉下来却是 master 分支
典型现象：明明写了 "dev-dev-auth-refactor"，vendor/acme/package/ 下却是 master 的代码。原因通常是：
- 没清空
vendor/和composer.lock，旧 lock 文件里还记着master的 commit hash - 分支名拼错（比如写成
"dev-auth-refactor"却实际是"dev/auth-refactor"—— Git 分支名含斜杠时，Composer 要求完整匹配） - 远程仓库权限不足，Composer 回退到 Packagist 上发布的默认版本（检查
composer update -vvv输出里是否有Cloning into日志）
分支拉取的本质是让 Composer 把 Git 仓库当成本地源来解析，而不是靠 Packagist 的版本索引。一旦配置生效，composer show acme/package 的输出里 versions 字段会显示类似 dev-dev-auth-refactor, dev-main，且 source 类型为 vcs —— 这才是真正的分支安装成功信号。
