Composer如何处理包的别名映射_Composer包别名alias配置规则【核心】-composer-PHP中文网

别名仅在repositories的package类型中生效，require中直接写"dev-main as 2.0.0"会报错；branch-alias仅用于vcs仓库且需在被依赖包自身composer.json中声明；别名不解决autoload冲突或conflict限制。

composer如何处理包的别名映射_composer包别名alias配置规则【核心】

别名只在 repositories 的 package 类型中生效

你在 require 字段里写 "monolog/monolog": "dev-main as 2.0.0"，Composer 会直接报错：Invalid version string "dev-main as 2.0.0"。别名不是 require 行的语法糖，它必须出现在 repositories 配置里，且仅对 "type": "package" 有效。

常见错误是只改 require，漏掉 repositories 定义。正确做法是：在 repositories 中加一个 fake package，明确指定 name、version（含 as）、dist.url 或 source.reference，再在 require 中按别名版本写依赖。

name 必须和 require 中的包名完全一致（大小写敏感）
version 字段必须存在，且格式为 "dev-main as 2.0.0"（as 前后各一个空格）
source.reference 要指向真实存在的 commit hash 或分支名，否则 composer update 会卡住或失败
as 右侧必须是合法语义化版本："2.0.0" ✅，"2.0" ❌，"latest" ❌，"2.0.x-dev" ✅

branch-alias 是包作者声明的开发分支映射

extra.branch-alias 是被依赖包自己在 composer.json 里写的配置，不是你项目里能随便加的字段。它只对 vcs 类型仓库（比如 GitHub）中的 dev- 开头分支生效，作用是让 ^2.0 这类约束能匹配到 dev-main 分支。

例如某库的 composer.json 里有：

{
  "extra": {
    "branch-alias": {
      "dev-main": "2.0.x-dev",
      "dev-next": "3.0.x-dev"
    }
  }
}

那你项目中写 "vendor/lib": "^2.0" 就会拉取它的 main 分支，并当作 2.0.x-dev 版本处理。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

键名必须带 dev- 前缀，即使 Git 分支叫 main，也要写 "dev-main"
值必须以 -dev 结尾："2.0.x-dev" ✅，"2.0.x" ❌
这个字段只在 VCS 包中起作用；path 类型仓库不支持 branch-alias
运行 composer show vendor/lib，如果显示 dev-main 2.0.x-dev，说明生效；只显示 dev-main 则配置未被读取

别名不解决类自动加载冲突

别名只是版本解析层的映射，它不会改变包的 autoload 配置，更不会隔离命名空间。两个包哪怕用了不同别名，只要都声明了 "psr-4": {"Monolog\": "src/"}，它们的类路径就会同时注册进 vendor/autoload.php。

一旦出现同名类（比如都定义了 MonologLogger），运行时必然报 Cannot declare class。

别名不影响 autoload 规则——类文件位置仍由包自身 composer.json 的 autoload 字段决定
无法靠别名绕过 conflict、replace 或 PHP 版本限制
如果真要共存同名包，必须确保它们的 autoload 命名空间前缀完全不同（如 "Monolog\" vs "AcmeMonolog\"），否则自动加载阶段就崩了