如何在 composer.json 中使用 conflict 字段来防止安装不兼容的包？

新闻中心 NEWS CENTER

2025-12-07

浏览次数：次

conflict 字段用于主动声明当前包与某些版本的其他包互不兼容，使 Composer 在安装或更新时检测到冲突即报错终止；其值为版本约束，如 "monolog/monolog": ">=2.0.0"。

在 composer.json 中使用 conflict 字段，是为了**主动声明当前包与某些版本的其他包互不兼容**，从而让 Composer 在安装或更新时直接报错，阻止不安全或不可用的组合被引入项目。

conflict 不是“建议不装”，而是“禁止共存”。只要 Composer 检测到当前依赖图中同时存在你声明的冲突包（且版本匹配），就会中断安装或更新，并抛出清晰的错误提示，例如：

"Package foo/bar v2.0.0 conflicts with my/project v1.5.0."

在 composer.json 的根级别添加 conflict 对象，键为包名，值为版本约束（支持通配符、比较符等）：

Openflow

一键极速绘图，赋能行业工作流

88 查看详情 Openflow

"conflict": {
    "monolog/monolog&quot;: ">=2.0.0",
    "phpunit/phpunit": "<9.0.0 || >=10.0.0",
    "ext-sodium": "<1.0.0"
}

上面表示：本包不兼容 monolog/monolog 2.x 及以上、phpunit/phpunit 小于 9 或大于等于 10、以及 sodium 扩展低于 1.0.0 版本
版本写法与 require 完全一致，支持 ^、~、!=、|| 等逻辑
可以冲突扩展（ext-xxx）、PHP 版本（php）、甚至自己（如 "my/package": ">=3.0.0" 表示不兼容自身未来大版本）

API 破坏性变更后封禁旧版依赖：比如你重构了对 guzzlehttp/guzzle 的调用方式，只支持 v7+，就加 "guzzlehttp/guzzle": "
避免运行时冲突：两个包都注册同名全局函数或重写同一类，可提前用 conflict 阻断
限制 PHP 或扩展版本：如强制要求 ext-mbstring 存在且不低于某版本，否则直接失败
防止误升级导致崩溃：某次发布明确不支持 Lar*el 10，就在 conflict 中写 "lar*el/framework": "^10.0"