分支别名（branch-alias）是让 composer 将 dev- 开头的开发分支映射为语义化版本（如 "dev-main": "2.0.x-dev"），解决非稳定分支无法被版本约束（如 "^2.0"）正常依赖的问题。
什么是分支别名（branch-alias），它解决什么问题
当你在开发一个尚未发布稳定版的 Composer 包（比如还在 dev-main 或 dev-develop 分支上迭代），而另一个项目想通过版本约束（如 "^2.0"）来依赖它时，Composer 默认会拒绝——因为分支不是正式版本。分支别名就是告诉 Composer：“把这条开发分支当作某个语义化版本来对待”。本质是给非稳定分支打一个“虚拟版本标签”，让 composer require 和 composer update 能正常解析依赖关系。
如何在 composer.json 中配置 branch-alias
分支别名必须写在被依赖方（即你正在开发的那个包）的 composer.json 里，且只对 dev- 开头的分支生效。关键点：它不是根级字段，而是放在 extra 下的子键：
{
"name": "myorg/my-package",
"type": "library",
"extra": {
"branch-alias": {
"dev-main": "2.0.x-dev"
}
}
}
常见配置组合：
-
"dev-main": "2.0.x-dev"→ 表示 main 分支等价于未来 2.0 系列的开发快照 -
"dev-develop": "1.9.x-dev"→ develop 分支不急于升 2.0，先作为 1.9 的预发布通道 - 多个分支可同时定义，但每个分支只能映射一个别名；别名末尾必须带
-dev - 别名不能是完整版本号（如
"2.0.0"），否则 Composer 会忽略它
为什么你的别名没生效？几个高频踩坑点
配置写了却不起作用，大概率掉进了这些坑里：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 你在「依赖方」而非「被依赖方」的
composer.json里加了branch-alias—— 它只在被引用的包中起作用 - 目标分支当前没有被推送（
git push origin main），或未被 Packagist/私仓索引到 - 你用的是
require的具体分支名（如"myorg/my-package": "dev-main"），此时别名不参与解析；只有写成版本约束（如"^2.0"）才会触发别名匹配 - 别名格式错误：
"dev-main": "2.0.x"缺少-dev后缀，或写成"2.0.x-dev-dev"多余后缀 - 本地开发时用了
path仓库类型，而path类型不读取branch-alias—— 这是设计使然，别名只用于 VCS 仓库（git）场景
配合 minimum-stability 和 prefer-stable 使用才完整
即使别名配对成功，依赖方默认仍可能跳过 -dev 版本。需要显式允许不稳定包：
{
"minimum-stability": "dev",
"prefer-stable": true,
"require": {
"myorg/my-package": "^2.0"
}
}
说明：
-
minimum-stability决定最低接受的稳定性标识（dev、alpha、beta等），设为dev才能匹配2.0.x-dev -
prefer-stable: true会让 Composer 在满足约束的前提下优先选稳定版（比如已有2.0.0就不会退回到2.0.x-dev） - 如果只想对某一个包放宽限制，可用
"myorg/my-package": "dev-main as 2.0.x-dev"这种内联别名写法，但仅限于 require 行，无法复用
分支别名本身不改变代码行为，但它决定了 Composer 能否把开发中的分支纳入版本决策树——漏掉任何一环（被依赖方配置、依赖方稳定性策略、VCS 可见性），整条链就断了。
