Composer 的 package alias 是用于 fork 替换场景的版本映射机制，格式为 "dev-branch as X.Y.Z"，仅在 repositories vcs 源中生效，使开发分支兼容原包依赖约束。
什么是 Composer 的 package alias（包别名）
Composer 本身不支持给已发布包“起别名”这种操作，比如把 monolog/monolog 叫成 my/log —— 这不是 Composer 的设计目标。所谓“alias”，实际只在一种场景下生效：当你 fork 一个包并修改后，想让它兼容原包的依赖声明。例如项目依赖 symfony/console:^5.4，但你用了自己 fork 的 my-fork/console，就需要用 replace + provide 或 repositories 配合 alias 来“冒充”原包。
如何用 repositories + package alias 替换依赖
这是最常见、也唯一被 Composer 官方支持的 alias 使用方式。核心是：在 composer.json 中添加自定义仓库，并在该仓库定义中用 alias 指向某个具体 commit 或分支的版本号。
-
repositories必须是vcs类型（如 git），且 URL 指向你的 fork 仓库 -
alias不是独立字段，而是写在require中的版本约束里，格式为"dev-main as 2.0.0" - 这个
as后面的版本号，必须和原包在其他依赖中声明的版本约束匹配（比如别人 require"some/package": "^2.0"，你就得 alias 成2.0.0或2.0.999） - 注意：alias 只对当前 require 生效，不会影响全局包名解析
示例：
OpenClaw 技能 — 给定一个 GitHub 仓库 URL，自动解析出 owner/repo 名称，发现其中的 YAML/properties 配置文件及其配对的中文字段说明；在 `workspace/{repo}/` 目录下按同步日期（格式为 `YYYY-MM-DD`）创建时间戳子目录；写入 `.openclaw-config-state.json` 状态文件。每次用户提问前，先比对远程仓库当前 ref（如 `main` 或 `master`）的最新提交 SHA 与本地状态文件中记录的 SHA：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/some-package"
}
],
"require": {
"some/package": "dev-main as 2.0.0"
}
}
为什么 composer require some/package:dev-main --no-update 然后手动改 version 不行
因为 Composer 在安装时会校验包的 version 字段与实际 tag/commit 是否一致。如果你在 fork 的 composer.json 里硬写 "version": "2.0.0"，但没打对应 tag，composer install 会报错：Could not find package some/package with version 2.0.0。更糟的是，即使绕过校验，也会导致 autoload、autoload-dev 和 metadata 解析异常。
- 正确做法是：用
as语法在 require 行做映射，让 Composer 把dev-main这个开发分支当作2.0.0版本来解析依赖关系 - 别试图改 fork 仓库里的
composer.json的version字段来“伪装”——它只在 packagist 发布时有意义，本地 vcs 仓库不读这个字段做版本判定 - 如果需要长期维护，建议在 fork 仓库中打一个真实 tag（如
v2.0.0-myfix），然后 require"some/package": "2.0.0-myfix"，比 alias 更稳定
alias 常见失败原因和调试方法
alias 失效往往不是语法错，而是逻辑不匹配。运行 composer show some/package 后发现版本仍是 dev-main？说明 alias 没被触发。检查以下几点：
- 确认
repositories的url能被 Composer 正确 clone（可手动git clone测试） - 确认你 require 的包名和
repositories中仓库的name字段（或其composer.json中的name）完全一致，大小写都不能错 - 运行
composer update --dry-run -v，看输出里是否出现Resolving dependencies through SAT并提及你的 alias 版本；如果没有，说明 Composer 根本没走你的仓库 - 别在
require-dev里用 alias 试图覆盖require中的包——Composer 不支持跨段覆盖
alias 是个窄带技巧，只在 fork 替换+版本对齐时有用。一旦涉及多版本共存、符号链接或自动加载路径重定向，就得换方案：比如用 path repository、autoload 的 files 或 psr-4 映射，而不是硬拗 alias。
