prefer-stable 是 composer 的配置项,用于在满足版本约束时优先选择 stable 版本而非 alpha/beta/rc/dev;默认不开启是因为语义化版本约束本身允许匹配不稳定版本,避免意外安装 pre-release 包。

prefer-stable 是什么,为什么默认不开启
prefer-stable 是 Composer 的一个配置项,它告诉 Composer:在满足版本约束的前提下,优先选择标记为 stable 的版本(比如 1.2.3),而不是 dev-、alpha、beta 或 rc 这类不稳定版本。
Composer 默认不开启它,是因为语义化版本约束(如 ^1.2)本身允许匹配 1.2.4(stable)或 1.3.0-beta.1(unstable)——只要后者满足约束。不开 prefer-stable,就可能意外装上 beta 包,尤其当包作者发了新 pre-release 但没及时打 stable tag 时。
怎么全局或项目级启用 prefer-stable
两种方式,选其一即可:
- 项目级(推荐):在项目根目录的
composer.json中加一行:"prefer-stable": true
- 全局级(慎用):运行命令
composer config -g prefer-stable true,会影响所有后续项目,容易在 CI 或协作中引发隐性不一致
注意:prefer-stable 不是开关式强制——它只在多个候选版本都满足约束时起作用。比如你写 "monolog/monolog": "2.0.*@dev",那它照样装 dev-master,因为约束本身已明确要求 unstable。
和 stability flags 冲突时谁赢
当 prefer-stable 和显式稳定性标记共存,后者优先级更高:
-
"foo/bar": "^1.0"+"prefer-stable": true→ 选1.0.5而非1.1.0-rc1 -
"foo/bar": "^1.0@beta"+"prefer-stable": true→ 仍选1.1.0-beta.2,因为@beta显式覆盖了偏好 -
"foo/bar": "^1.0@stable"→ 即使没开prefer-stable,也只找 stable 版本
常见坑:有人以为开了 prefer-stable 就能“屏蔽 beta”,结果发现还是装了 rc 版——大概率是依赖树里某个包的 require 写了 @rc,或者你用了 minimum-stability 降级到 RC。
minimum-stability 和 prefer-stable 的关系
minimum-stability 是底线,prefer-stable 是倾向:
-
"minimum-stability": "stable"→ 只允许安装 stable 版本,prefer-stable无意义(没得选) -
"minimum-stability": "beta"→ 允许 stable / beta / rc,此时prefer-stable: true才真正起效:有 stable 就不用 beta - 如果设了
"minimum-stability": "dev",又开了prefer-stable,它依然会优先 stable,但不会拒绝 dev —— 只要没别的 stable 满足约束,它还是会退到 dev
最易忽略的一点:修改 prefer-stable 后必须重新运行 composer update,否则 lock 文件不会更新——旧的不稳定版本可能被锁死,光改配置没用。










