Composer 2.0+ 已彻底弃用 branch-alias，不再解析 extra.branch-alias 配置；应改用 version 字段设为 3.0.x-dev、配合 --stability=dev 或 VCS 仓库直接引用 dev-main 分支，并优先通过 Git tag（如 v3.0.0）实现版本约束兼容。
Composer 中的 branch-alias 已在 Composer 2.0+ 中被正式弃用，**不再推荐、也不再生效**。如果你在 composer.json 的 extra 里还写着 "branch-alias": {"dev-main": "2.0.x-dev"}，它不会影响安装行为，也不会解决版本约束问题。
为什么 branch-alias 不再起作用
Composer 1.x 时期，branch-alias 是为了解决“开发分支（如 dev-main）如何被当成稳定版本别名（如 2.0.x-dev）来 require”的问题。但它的设计有根本缺陷：依赖方无法感知别名，且与语义化版本（SemVer）冲突。Composer 2.x 起彻底移除了对它的解析逻辑 —— 任何写在 extra.branch-alias 里的内容都被忽略。
常见错误现象：
- 运行
composer require vendor/package:dev-main失败，提示“could not find package”或版本不匹配 - 即使写了
"branch-alias": {"dev-main": "3.0.x-dev"}，composer show vendor/package仍显示dev-main，而非3.0.x-dev - 其他项目
require "vendor/package": "^3.0"无法匹配到你的dev-main分支
替代方案：用 stability flags + version constraint 显式声明
真正可控、兼容 Composer 2.x 的做法，是放弃“自动别名”，改用明确的稳定性标记和版本约束组合。核心思路是：让分支本身带符合 SemVer 的开发版本号，并通过 minimum-stability 和 prefer-stable 控制解析行为。
实操建议：
- 在你的包的
composer.json中，把version字段设为开发版格式，例如"version": "3.0.x-dev"（仅用于本地开发/私有仓库场景；公开 Packagist 包不应设version） - 确保
branch-alias完全删除，避免误导维护者 - 在使用方项目中，显式 require 开发版本：
composer require vendor/package:3.0.x-dev
- 若需放宽约束（比如允许
^3.0匹配3.0.x-dev），必须同时满足：- 包的
composer.json中type为library（默认值） - 使用方设置了
"minimum-stability": "dev"（不推荐全局设，仅临时加在 require 命令后） - 更安全的做法是：用
--stability=dev参数：composer require vendor/package:^3.0 --stability=dev
- 包的
私有仓库或 Git 仓库的正确引用方式
如果你控制的是私有包或 Git 仓库，最可靠的方式不是靠别名，而是直接用 VCS 路径 + 分支名 + 稳定性标记：
- 在使用方的
composer.json中添加仓库配置：{ "repositories": [ { "type": "vcs", "url": "https://git.example.com/vendor/package.git" } ] } - 然后 require 分支并指定稳定性：
composer require vendor/package:dev-main --stability=dev
- 注意：
dev-main会被解析为9999999.9999999.9999999-dev（Composer 内部标记），所以^3.0这类约束依然不匹配 —— 必须显式写dev-main或改用3.0.x-dev标签
真正要让旧版约束（如 ^2.5）兼容新分支，唯一可依赖的是 Git tags：打一个 v2.5.0 或 2.5.0 tag，比任何别名都管用。别名机制已死，标签和明确的 -dev 版本号才是现在唯一的事实标准。
