Composer 的 alias 机制通过版本别名（如 "dev-main as 2.0.x-dev"）解决同名包冲突，需在 repositories 中定义 package 类型并正确配置 version 字段，仅影响版本解析而非包名或自动加载。
composer require 时提示 “Package … is already present” 却装不上新包
这是 alias 最常被触发的场景：你想通过 composer require vendor/new-package 引入一个包，但 Composer 报错说同名包已存在（比如本地已有 vendor/old-package），而你又不能删旧包——因为项目强依赖它。这时候别急着改 autoload 或 fork 重命名，composer.json 的 repositories + alias 就是为此设计的。
核心思路不是“覆盖”，而是“映射”：让 Composer 认为 vendor/new-package 是另一个名字，从而绕过冲突校验。
- 必须把新包加进
repositories，类型设为vcs或package，不能只写require -
alias只在repositories的单个包定义里生效，格式是"version": "dev-main as 2.0.x-dev"这种，注意as前后要有空格 - 别名版本号必须是合法的 Composer 版本约束（如
1.2.3、dev-main、^2.0），不能写latest或master - 如果原包用的是
dev-main，别名写成"dev-main as 3.0.x-dev"后，require里就得写"vendor/new-package": "^3.0"，否则匹配不上
alias 不生效？检查是否漏了 version 字段或拼写错误
alias 本质是版本别名，不是包名别名。很多人以为加了 "alias": "new-name" 就行，但 Composer 根本不认这个 key——alias 必须作为 version 的一部分出现，且只接受 as 语法。
常见失效现象：composer update 没报错，但 vendor/autoload.php 里还是加载不到新包类，或者 composer show 列不出别名版本。
- 确认
repositories里该包定义中，version字段存在且含as，例如："version": "dev-feature/login as 1.5.0" - 检查包的
name字段是否和require中完全一致（包括大小写），Composer 对 name 是严格字符串匹配 - 运行
composer update --dry-run看实际解析出的版本号，确认是否命中了你写的别名版本 - 别名只影响安装时的版本解析，不影响自动加载路径——类文件位置仍由包自身
autoload配置决定
多个同名包共存：用 alias + 自定义 repository 分开管理
当项目同时需要 monolog/monolog 的官方版和某公司魔改版（比如叫 acme/monolog），但两者都声明自己是 monolog/monolog，就会冲突。这时不能只靠 alias，得配合自定义 repository 类型。
做法是把魔改版单独放进一个 package 类型仓库，并用 alias 给它“换身份”：
{
"repositories": [
{
"type": "package",
"package": {
"name": "monolog/monolog",
"version": "2.9.0-acme as 2.9.0-acme",
"dist": {
"url": "https://example.com/monolog-acme-2.9.0.zip",
"type": "zip"
},
"autoload": { "psr-4": { "Monolog\": "src/" } }
}
}
],
"require": {
"monolog/monolog": "^2.9.0-acme"
}
}
-
package类型仓库必须提供完整包信息，缺autoload会导致类无法加载 - 别名版本号（如
2.9.0-acme）要确保不和现有任何版本冲突，否则 Composer 会拒绝安装 - 这种方案适合少量关键包；如果要管理十几个同名包，建议统一迁移到私有 Packagist，而非堆砌
repositories
alias 和 replace 的区别：什么时候该用 replace？
alias 解决的是“同一个包名，多个实现”的安装问题；replace 解决的是“一个包，替代另一个包”的依赖替换问题。两者目的不同，混用反而容易翻车。
典型误用：想用自研缓存组件替代 cache/cache，于是在自己的包里写 "replace": {"cache/cache": "*"}，结果项目里其他包依赖 cache/cache 的接口，却没做适配——运行时报 Class not found。
-
replace是告诉 Composer：“我这个包已经包含了被替换包的所有功能”，Composer 会跳过安装被替换包，但不会帮你做接口兼容 -
alias不改变依赖图，只是给某个具体 commit 或分支贴个新版本标签，安全边界更清晰 - 如果真要替代，优先用
provide+ 接口抽象（如psr/cache-implementation），而不是硬 replace - alias 修改的是版本识别逻辑，replace 修改的是依赖解析逻辑——前者影响 install，后者影响 resolve
alias 看似简单，但它的生效前提是整个依赖图里没有其他包硬编码依赖某个特定版本字符串。一旦有包在代码里写了 if (version_compare($v, '2.8.0', '>='))，而你 alias 成 2.8.0-custom，那个判断就失效了。这点很容易被忽略。
