在PHP生态里跟Composer打交道，版本约束这事儿，说大不大，说小还真不能马虎。特别是当你需要直接装一个开发中的分支——比如 dev-main——来验证某个新功能或修复时，命令怎么写、背后有哪些坑，其实有不少讲究。今天就用几个实际场景，把这件事彻底讲清楚。
composer require 怎么装 dev-main 或其他分支
是不是直接 composer require vendor/package:dev-main 就完事了？理论上是，但你得先确认两个前提：项目的 minimum-stability 配置允许不稳定包，并且目标仓库确实有这个分支。默认情况下，Composer 的稳定性门槛是 stable，所以不加任何额外参数，大概率会收到一个“no matching package found”的错误。
最常见的正确做法是加上 --stability=dev 参数：
composer require monolog/monolog:dev-main --stability=dev这里有几点必须留意：
- 分支名是大小写敏感的。
dev-main是对的，写成dev-Main就找不到。 - 有些项目还在用
master分支，那你得写dev-master，不是所有仓库都已经切到main。 dev-main本质上不是版本号。每次composer update都会拉取最新的提交，这就意味着你的依赖是不稳定的。生产环境或 CI 流程中依赖它，等于给自己埋雷。- 如果你的仓库是私有的，必须在
composer.json的repositories字段中显式声明type为vcs，否则 Composer 根本不会去查那个地址。
dev- 分支 + #commit hash 怎么写才生效
想把依赖锁定到某一次特定的提交，写法可不是简单的 dev-main#abc123 就万事大吉。Composer 需要你明确告诉它“这是源码模式”，否则它可能会悄悄 fallback 到 dist 包，或者干脆执行失败。
正确的姿势是这样的：
composer require vendor/package:dev-main#abc123 --prefer-source拆解一下这里的关键点：
--prefer-source强制 Composer 从 Git 克隆源码，这样才能确保composer.lock中的source.reference记录的是你指定的那个 hash。- 你指定的 hash 必须存在于目标分支的历史中。比如
abc123得实实在在是main分支上的一个提交，否则还是失败。 - 如果你写了
dev-main#abc123却忘了加--prefer-source，Composer 很可能会忽略后面的 hash，只安装分支的最新 HEAD。 - 执行之后，一定要去检查
composer.lock文件。确认对应包的source.type是git，source.reference的值就是你输入的那个 hash。这一步能堵住大部分“明明锁了却还是变了”的坑。
为什么写了 dev-main 还装了 stable 版本
这是非常常见的一个问题：明明命令输入正确，结果却装了个稳定版。原因通常只有一个——你当前的 composer.json 里已经有其他约束在作祟。
举个例子，你运行了 composer require monolog/monolog:dev-main --stability=dev，但如果 composer.json 里原来就有一条 "monolog/monolog": "^2.8"，Composer 会优先满足已有的约束，而不是你刚输的命令。
解决方案很直接：
- 先删除旧约束：
composer remove monolog/monolog - 然后再装分支版本：
composer require monolog/monolog:dev-main --stability=dev - 或者更干脆，手动打开
composer.json，把该包的条目清掉，再运行 require 命令。
还有一个不太容易被注意的干扰因素：config.platform 里如果锁死了 PHP 版本，某些 dev 分支可能因为与锁定的 PHP 版本不兼容而被自动跳过。当你看到“Your requirements could not be resolved”这样的错误时，不妨往下多看几行，是否跟着 platform 不匹配的提示。
dev 分支和 exact tag 混用时的冲突风险
一个项目里同时出现 "package-a": "dev-main" 和 "package-b": "3.2.1" 并不罕见。问题在于，package-b 的新功能可能依赖于 package-a 的某个尚未发布的 API。这时候跑 composer update，很可能触发隐式升级或者版本冲突。
事情会怎么发展呢？Composer 会尽力找一个同时满足 dev-main（版本上限无限）和 3.2.1（精确锁死）的解。大多数情况下它能做到，但这种“大部分时候能跑通”的状态其实很危险。假如 package-a 的 dev 分支引入了不兼容的改动，package-b 可能在运行时直接崩溃。
更致命的是，这种混合组合没法靠 composer.lock 完全兜底。lock 文件能固化的只是当前 commit，但下次 update 时，dev 分支会拉取新提交，而 exact tag 那一方不会动。时间一长，你的依赖状态就变成了一个“幽灵组合”——没有人敢动，也没有人能说清楚它到底包含了哪些代码。
真正可控的做法是：把 dev 分支也钉到一个具体的 hash 上，并且在团队文档里写清楚这个 hash 对应的语义——比如“包含 XXX 修复，待发版 3.3.0”。
说到底，用 dev 分支不是为了图省事，而是为了验证未发布的变更。但凡涉及到协作或者生产环境部署，就得把它当成一个临时状态来管理——写死 hash、注明用途、及时替换为正式 tag。否则，它迟早会变成一个没人敢动的“幽灵依赖”。
