composer别名仅用于版本解析，不解决运行时冲突；必须在require中用“dev-branch as x.y.z”格式，且需满足分支真实、语义化版本合法、空格唯一三条件；repositories+package才是接管版本的正确方式。
Composer 里没有“给包起新名字”的别名功能，所谓“定义别名”实际是让某个分支或 commit 假装成一个合法语义化版本，仅用于绕过依赖解析阶段的版本冲突。它不改代码、不补方法、不解决运行时类冲突，用错直接导致 Call to undefined method 或 Cannot declare class。
require 中写 "dev-branch as X.Y.Z" 是唯一生效位置
这个语法只在 require 或 require-dev 字段里被识别，且必须满足三个硬性条件：
-
dev-branch部分必须指向真实存在的分支或 commit（比如dev-fix-auth），不能是空想出来的名字 -
as后面必须是合法语义化版本，如2.9.2、3.0.x-dev，不能是latest、master、2.9（缺位数）或dev-3.0 - 中间必须有且只有一个空格：
"dev-fix as 2.9.2"✅，"dev-fix as2.9.2"❌
常见错误是把它当字符串替换用，比如写成 "monolog/monolog": "dev-main as 3.0.0" 后发现 composer install 完全没反应——因为 install 只读 composer.lock，必须跑 composer update monolog/monolog 才会重新解析 alias。
repositories + type: package 是真正接管版本的写法
如果你要 fork 一个包并让它“冒充”原版稳定版本，require 行里的 as 不够用，必须配合 repositories 显式声明一个假包：
-
name字段必须和require中完全一致（大小写敏感），否则 Composer 根本不认这是同一个包 -
version字段必须存在，且格式为"dev-main as 2.0.0"，as前后各一个空格 -
source.reference必须是真实可拉取的 Git 分支名或 commit hash；填错会导致composer update卡住或报Could not fetch - 如果原包要求 PHP >=8.2，而你系统是 8.3，别名也救不了——
conflict字段和platform检查照常生效
验证是否生效：运行 composer update --dry-run，看输出里是否出现类似 - Installing monolog/monolog (2.0.0): Cloning abc123 from dev-main 的行。如果还显示 dev-main，说明 alias 没被识别。
branch-alias 是包作者该做的事，不是你项目里能加的
extra.branch-alias 必须写在**被依赖包自身**的 composer.json 里，例如：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"extra": {
"branch-alias": {
"dev-main": "2.0.x-dev"
}
}
}
它只对 VCS 类型仓库（GitHub/GitLab）有效，且只在你用版本约束（如 "myorg/lib": "^2.0"）安装时才触发。如果你直接写 "myorg/lib": "dev-main"，这个 alias 就完全不参与解析。
常见失效原因：
- 你在自己的项目
composer.json里加了branch-alias——它只在被引用方生效 - 分支名没加
dev-前缀，比如写了"main": "2.0.x-dev"，但正确写法必须是"dev-main": "2.0.x-dev" - 值末尾没带
-dev，如"2.0.x"会被忽略 - 你用的是
path类型本地仓库，这种类型根本不读branch-alias
别名解决不了 autoload 和命名空间冲突
两个包都声明 "psr-4": {"Monolog\": "src/"}，哪怕用了不同别名，vendor/autoload.php 仍会把它们的路径都注册进去。一旦都定义了 MonologLogger，运行时必报 Cannot declare class。
别名只影响依赖解析器对版本号的判断，不改变以下任何一项：
- 自动加载路径注册顺序（后注册的覆盖先注册的）
- 类文件实际内容是否兼容（alias 成
3.0.0但删了Logger::pushHandler()？运行就崩） - PHP 版本、扩展、
conflict声明等底层限制
最常被忽略的一点：别名生效后，composer show monolog/monolog 输出的 versions 里会列出你写的别名版本（如 * 2.0.0），但 version 字段仍显示原始分支名（如 dev-main）。别只看 version 就以为没生效。
