branch-alias是Composer中用于将开发分支映射到预期稳定版本的配置,通过extra.branch-alias指定,如"dev-main": "2.0.x-dev",使依赖包能以语义化版本格式引用开发中的分支,便于版本约束和升级管理。

在 composer.json 中使用 branch-alias 可以为开发分支(如 dev-main 或 dev-develop)设置版本别名,方便其他包依赖时使用语义化版本格式进行约束。
什么是 branch-alias?
branch-alias 不是给分支起别名,而是告诉 Composer:某个开发分支将来会发布成哪个稳定版本。这主要用于 dev- 分支,让依赖该分支的项目可以用类似 @dev 或版本约束(如 ^2.0-dev)正确解析。
如何配置 branch-alias
branch-alias 配置在 extra 字段下,结构如下:
{
"extra": {
"branch-alias": {
"dev-main": "2.0.x-dev",
"dev-develop": "2.1.x-dev"
}
}
}
说明:
-
dev-main是实际的 Git 分支名 -
2.0.x-dev是为该分支指定的别名版本 - 别名格式通常为
{major}.{minor}.x-dev
使用场景与作用
假设你维护一个库,主分支是 main,即将发布 2.0 版本。其他项目想提前测试 2.0 功能,会这样依赖:
"your/package": "2.0.x-dev"
如果没有 branch-alias,Composer 无法知道 2.0.x-dev 对应哪个分支。加上 alias 后,Composer 就能正确映射到 dev-main 分支。
常见用途包括:
- 支持多个开发线(如 2.0 开发中,同时 3.0 在 develop 分支)
- 避免下游项目直接写
dev-main,提高可读性和兼容性 - 配合版本约束实现平滑升级
注意事项
branch-alias 只影响 dev 分支的版本解析,不会改变实际分支名或标签。
- 必须发布新版本后才能生效(即使只是更新 composer.json)
- 只在 VCS(如 Git)仓库中有效
- 建议每个主要开发分支都设置清晰的 alias
基本上就这些。合理使用 branch-alias 能让包的版本管理更清晰,也方便使用者理解开发进度。










