在使用 Composer 管理 PHP 项目依赖时，有时你需要让其他项目依赖你正在开发中的分支（如 dev-main 或 dev-develop），但又希望它能匹配某些版本约束（例如 ^2.0）。这时就可以通过 branch-alias 来为开发分支定义一个“虚拟”的稳定版本号。

什么是 branch-alias？

branch-alias 是 composer.json 中的配置项，用于将某个开发分支映射到一个假想的版本号。这样即使你的代码还在开发中（比如还在 main 分支），也能被当作某个稳定版本来引用。

这在以下场景非常有用：

• 你想测试一个尚未发布正式版本的包
• 你在 CI/CD 中依赖开发分支，但要求版本约束匹配（如 ^2.0）
• 你希望别人用 "your/package": "^2.0" 安装时，能拉取你 main 分支的最新代码

如何配置 branch-alias

在你的包的 composer.json 文件中添加 extra 字段下的 branch-alias 配置：

{
    "name": "you/your-package",
    "version": "dev-main",
    "extra": {
        "branch-alias": {
            "dev-main": "2.0.x-dev"
        }
    }
}

上面这段配置的意思是：

Zapier推出的Agents智能体，集成7000+应用程序

• 当前 main 分支会被当作 2.0.x-dev 版本来处理
• 其他项目就可以用 "you/your-package": "^2.0" 来依赖这个开发分支

常见用法示例

假设你正在开发一个 3.0 版本的新功能，放在 develop 分支上：

{
    "name": "you/your-package",
    "extra": {
        "branch-alias": {
            "dev-develop": "3.0.x-dev"
        }
    }
}

然后在另一个项目中，你可以这样写：

"require": {
    "you/your-package": "^3.0"
}

Composer 会自动拉取你仓库的 develop 分支，并将其视为满足 ^3.0 的版本。

注意事项

• branch-alias 只对开发分支有效（如 dev- 前缀的分支）
• 别名格式通常为 {major}.{minor}.x-dev，不能是完整版本如 2.0.0
• 必须提交到对应分支才能生效（即在 main 分支上的 composer.json 才会影响 dev-main）
• 不需要为已打 tag 的版本设置别名

基本上就这些。合理使用 branch-alias 能让你的开发流程更灵活，尤其是在多项目协作或提前集成测试时特别方便。