Composer如何管理包的多版本分支_Composer包多版本分支管理要点-composer-PHP中文网

composer 不管理分支版本，仅按 composer.json 约束匹配 git 分支或 tag；dev-分支名须与 git 实际分支完全一致、区分大小写、含斜杠需保留 dev- 前缀；branch-alias 仅用于包作者声明别名供他人引用；require dev-分支需配合 --stability=dev 参数；dev 分支 commit hash 被锁入 composer.lock，force push 会导致失效；生产环境应避免长期依赖 dev 分支。

composer如何管理包的多版本分支_composer包多版本分支管理要点

Composer 本身不“管理”分支版本，它只是按你写的约束去匹配 Git 分支或 Tag —— 真正的控制权在 composer.json 的写法、Git 仓库状态和 Packagist 同步节奏上。

dev-分支名必须和 Git 实际分支名完全一致

比如你在 Git 仓库里只有 main 分支，那只能用 dev-main；如果误写成 dev-master 或 dev-main2，Composer 就会报 Could not find a version of package xxx matching your minimum-stability。

分支名区分大小写：dev-Main ≠ dev-main
含斜杠的分支（如 feature/login）必须写成 dev-feature/login，不能省略 dev- 前缀
私有仓库若用 SSH 地址（如 git@gitlab.example.com:acme/utils.git），需确保运行 composer install 的机器已配置对应 SSH key

branch-alias 只在发布包的 composer.json 中生效

branch-alias 是给「别人引用你这个包」时用的，不是给自己项目配的。它只起作用于你作为包作者，在自己包的 composer.json 的 extra 段里声明：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

"extra": {
    "branch-alias": {
        "dev-main": "1.0.x-dev"
    }
}

键名 dev-main 必须和真实 Git 分支名一模一样
值 1.0.x-dev 是别名，供其他项目写 "acme/utils": "^1.0" 时能命中该分支
这个 alias 不影响 dev-main 本身的安装行为，也不改变 Packagist 对分支的识别逻辑

require 中写 dev-分支时，minimum-stability 往往要临时放宽

默认 minimum-stability 是 stable，而 dev-main 属于不稳定版本，直接 composer require vendor/package:dev-main 会失败。

最安全做法：加 --stability=dev 参数，如 composer require monolog/monolog:dev-main --stability=dev
不推荐永久改 composer.json 的 minimum-stability，否则所有依赖都可能降级到 -dev 版本，带来不可控风险
如果已设为 dev 却仍失败，检查是否漏了 repositories 配置 —— 尤其是私有包，没声明源就等于“不存在”

dev-分支的 commit hash 被锁进 composer.lock，但 force push 会导致失效

执行 composer update vendor/package 后，composer.lock 会记录该分支当前 HEAD 的完整 commit hash。下次 install 就按这个 hash 拉取。

但如果原分支被 git push --force 覆盖，旧 hash 就失效，composer install 会报 Failed to download ... Could not load package ... No valid composer.json was found
这不是 Composer 的 bug，是 Git 语义决定的 —— dev 分支本就不承诺稳定性
生产环境应尽量避免长期依赖 dev- 分支；真要灰度测试，可用 "dev-main as 1.2.3" 临时伪装成稳定版，但上线前务必切回正式 Tag

真正容易被忽略的是：分支名、Tag 名、composer.json 里的 version 字段三者之间没有强制同步机制。一个写错，Packagist 就拒绝同步，或者 CI 构建时解析出错 —— 这类问题往往要翻好几层日志才能定位。