必须用“as”语法将dev-main等分支伪装成合法版本号（如“dev-main as 2.0.0”）才能安装，否则Composer因不识别分支名为有效版本而报错；as是强制版本映射，影响依赖解析与锁文件记录。
dev-main 或 dev-feature/x 不能直接 require，必须加 as
Composer 默认把 dev-main、dev-feature/new-api 这类分支名当“无版本”处理，不参与语义化版本匹配。你写 "vendor/name": "dev-main"，哪怕仓库存在，也会报错“could not find package matching constraint”。真正起效的写法是强制绑定一个合法版本号："vendor/name": "dev-main as 2.0.0"。这个 as 不是装饰，是让 Composer 把整个分支“当作” 2.0.0 来解析依赖图——后续所有版本约束（比如 ^2.0）、锁文件记录、更新行为，都按这个假版本走。
常见错误包括：
- 漏掉
dev-前缀，写成"main as 2.0.0"→ Composer 根本不认识 -
as右侧用了非法字符串，比如"dev-main as latest"或"dev-main as 2.0.x"→ 必须是符合 SemVer 的完整版本号（2.0.0、2.5.0-beta1、3.0.0-rc2） - 在
repositories里配 alias → 完全无效，别名只在require或require-dev字段中生效
装 beta/alpha/RC 时，as 别名和 @beta 冲突吗？
不冲突，但用法完全不同，且不能混用。如果你要装的是远程已打 tag 的 2.5.0-beta1，最干净的做法是直接写："vendor/name": "2.5.0-beta1" 或 "vendor/name": "^2.5@beta"，根本不需要 as。只有当你想用一个尚未打 tag 的开发分支（比如 dev-main），又希望它满足 ^2.5 这类约束时，才需要 as 绑定一个对应版本号，例如："vendor/name": "dev-main as 2.5.0-beta1"。
注意两个关键点：
-
@beta是稳定性标记，告诉 Composer “允许降级到 beta 级别”，而as是版本映射，改变的是 Composer 对该包“是什么版本”的认知 - 不要写
"dev-main as 2.5.0-beta1@beta"——@beta在这里多余且会触发解析错误 - 如果包本身
composer.json里声明了"version": "dev-main"，那2.5.0-beta1这个 tag 就不会被识别，必须确认远程仓库真实打了对应 tag
装完发现 composer show 显示的还是旧版本？检查 lock 文件和依赖图
运行 composer require vendor/name:dev-main as 2.0.0 成功，不代表实际装上了。最常踩的坑是 composer.lock 里还存着旧版本记录，Composer 优先信任 lock 文件，不会重新解析别名。此时 composer show vendor/name 显示的仍是之前锁定的版本。
解决办法分三步：
- 删掉
composer.lock中该包的整段条目（或直接删整个 lock 文件，仅限调试） - 确保
require字段已更新为带as的写法 - 运行
composer update vendor/name --with-all-dependencies，强制重算依赖树并写入新 lock
另一个隐蔽原因是依赖冲突：比如另一个包 another/pkg 要求 vendor/name:^2.1，而你 alias 的是 2.0.0，Composer 会拒绝安装，连提示都可能很模糊。此时得调高 alias 版本（如 2.1.0）或检查上游约束。
别名不是万能的，IDE 和静态分析可能“看走眼”
as 是 Composer 层的逻辑欺骗，它只影响依赖解析和自动加载路径，不改变源码内容。这意味着：
- PHPStan / Psalm 仍按你 fork 或 checkout 的真实代码做类型推导，不会因为 alias 成
2.0.0就去查官方2.0.0的接口定义 - IDE（如 PHPStorm）可能缓存了 alias 版本的 stub，导致方法提示和实际运行结果不一致——比如提示有
newMethod()，但你的分支还没实现它 - 如果你 alias 的版本号和原包最新稳定版不一致（比如原包最新是
2.9.2，你 alias 成2.5.0），其他依赖^2.9的包会直接失败，而不是静默降级
真正难处理的不是怎么写对 as，而是你得清楚自己 alias 的那个分支到底实现了多少功能、是否真兼容目标版本的契约。别名省了版本管理的麻烦，但没省掉兼容性验证的责任。
