Composer不支持require时直接设别名，仅两种合法场景：一是被依赖包在composer.json中用extra.branch-alias声明分支映射，二是在项目repositories中以package类型定义并用"version": "dev-main as 2.0.x-dev"格式配置。
Composer 本身不支持在 require 时直接给包起别名，所谓“alias”只有两种合法生效场景：一是被依赖包自己在 composer.json 中通过 extra.branch-alias 声明开发分支映射；二是在你自己的项目中用 repositories + type: "package" 手动定义一个带 "version": "dev-main as 2.0.x-dev" 的伪包。其他写法全都不生效。
为什么 composer require vendor/pkg as my-alias 会报错
这条命令根本不是 Composer 的语法——as 不是 require 的参数，也不是 composer.json 的顶层字段。你一敲就会看到：
Invalid version string "dev-main as 2.0.0"
原因很直接：as 只允许出现在 repositories 中某个 package 类型的 version 字段值里，且必须满足格式约束。
-
require字段只接受标准版本约束（如"^2.0"、"dev-main"、"=1.2.3"） - 想“换名字装”，必须走
repositories+package路线，把name设成你要的别名，再用dist.url指向真实源 - 别名不是终端指令，而是元数据映射规则，得提前写进配置，不是运行时动态指定
extra.branch-alias 必须写在被依赖包的 composer.json 里
这是唯一能让别人用语义化版本（比如 "^1.0"）拉到你 dev-main 分支的方式。但注意：它只对 vcs 类型仓库（如 GitHub）有效，且仅影响开发分支。
- 写法必须是：
"extra": { "branch-alias": { "dev-main": "1.0.x-dev" } } -
"dev-main"是 Git 分支名，"1.0.x-dev"是虚拟版本号，结尾必须带-dev，中间的x是占位符，不能省略 - 本地用
path仓库测试时，branch-alias不生效——Composer 直接读文件，跳过版本解析 - 运行
composer show vendor/pkg，如果输出里有1.0.x-dev，说明 alias 已被识别；如果只有dev-main，说明没生效
repositories.package 中的 as 写法和常见失效点
当你需要在项目中“接管”一个已存在包名（比如替换 monolog/monolog），就得靠这个方式。核心是伪造一个 package，并在其 version 字段里嵌入 as 映射。
-
name必须和require中完全一致（大小写敏感），否则匹配失败 -
version必须是完整字符串，例如："dev-main as 2.0.0"，不能是"dev-main as latest"或"dev-main as 2.0"（缺补零） -
dist.url必须指向可下载的 zip/tar 包，不能是 Git 地址；若用vcs类型，则as无效 - autoload 配置必须手动复制，别名不继承原包的自动加载规则——漏掉就
Class not found - 执行
composer update --dry-run，确认解析出的版本号是否为2.0.0，而不是继续锁定dev-main
别名不会解决兼容性问题，只是绕过解析校验
很多人加别名是为了躲开 Your requirements could not be resolved，但 alias 不改代码、不补方法、不处理 PHP 版本或 conflict 字段限制。它只是让 Composer “假装”那个版本存在。
- 如果原包声明了
"conflict": {"symfony/console": "^6.0"}，你 alias 成6.0.0也没用，冲突照样触发 - PHP 版本不匹配（比如包要求
php: ^8.2，而你环境是 8.1）时，alias 无法绕过 - 真正要验证是否能用，得看
composer why-not vendor/pkg:6.0.0，再手动检查拦路包是否真调用了被删 API - alias 后两个同名包共存（比如都注册了
Monolog\Logger），类加载路径会叠加，同名类冲突 runtime 必炸
最常被忽略的是：alias 是版本映射，不是命名空间重写，也不是自动加载代理。它只在依赖解析那一刻起作用，之后一切照旧——autoload 怎么配、类怎么写、文件怎么放，全得你自己对齐。
