Composer 中 package alias 须在 require 中用 "vendor/name": "dev-branch as 2.5.0" 语法，as 右侧为合法稳定版本号；生效需运行 composer update vendor/name 或重装，且依赖检查严格匹配别名版本。
composer.json 里怎么写 package alias
包别名（package alias）本质是让 Composer 把某个版本“假装成”另一个版本，常用于 fork 后保持兼容、或临时修复未合入主干的 PR。不是给包起昵称，而是重映射版本号。
必须在 require 或 require-dev 中用 "vendor/name": "dev-main as 2.5.0" 这种语法，as 前是真实来源（分支/commit），后面是你要它“冒充”的稳定版本号。
-
as右侧必须是合法的版本约束（如1.2.3、^2.0），不能是dev-master或dev-feature/x - 如果目标包原本要求
"some/pkg": "^3.0"，你 alias 成"3.0.0"才能通过依赖检查；alias 成"2.9.9"会报your requirements could not be resolved - 别在
repositories里配 alias——那里只管源，版本映射得在require层做
为什么 composer install 不生效 alias
最常见原因是锁文件（composer.lock）里还存着旧版本记录，Composer 优先信 lock 文件，不会重新解析 alias。
- 执行
composer update vendor/name（指定包名），而不是composer install - 或者删掉
composer.lock和vendor/后重装（仅调试时用） - 检查
composer show vendor/name输出的 version 字段：如果是dev-main但显示versions : * 3.0.0，说明 alias 生效；如果仍显示dev-main，说明没被识别
fork 后用 alias 替代原包的实操要点
想用自己 fork 的 monolog/monolog 替代官方版，同时让其他依赖继续认它为 ^2.9，就得靠 alias。
先在 repositories 加你的 fork：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/monolog"
}
]
再在 require 里写：
"monolog/monolog": "dev-fix-logging as 2.9.2"
- 分支名
dev-fix-logging必须存在于你的 fork 仓库中，且有composer.json（哪怕内容和原版一样） -
as 2.9.2要和原包最新2.9.x版本号一致，否则依赖它的包可能因版本不满足而失败 - 别漏掉
"type": "vcs"——用package类型手动定义时，alias 会被忽略
alias 会带来哪些隐性问题
它绕过了语义化版本校验，属于“骗过 Composer”，用得不当会导致行为不一致甚至运行时错误。
- 如果你 alias 成
3.0.0，但实际代码里删了某个3.0.0才有的方法，下游调用就会Fatal error: Call to undefined method - PHPStan / Psalm 静态分析仍按真实源码检查，但 IDE 可能按 alias 版本提示方法签名，出现提示和运行结果不一致
- 团队协作时，别人没跑
update或没拉最新 lock 文件，就可能本地还是旧版本，导致“在我机器上是好的”类问题
alias 不是长期方案，只是过渡手段。真正要替换包，最好推 PR、等发版，或者用 replace + provide 做更干净的替代。
